# XHDB

**Repository Path**: hamsterm/xhdb

## Basic Information

- **Project Name**: XHDB
- **Description**: 基于WCDB的数据库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-09-11
- **Last Updated**: 2023-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: IOS, Swift

## README

### 基于WCDB的数据库

[WCDB](https://github.com/Tencent/wcdb)是一个高效、完整、易用的移动数据库框架，基于[SQLCipher](https://github.com/sqlcipher/sqlcipher)，支持iOS, macOS和Android。

参考文档：https://github.com/Tencent/wcdb/wiki

<img src="https://gitee.com/hamsterm/upic_pic_bed/raw/master/upic/CodeStructure.png" alt="CodeStructure" style="zoom:50%;" />

- **XHDB 版本 vs Swift 版本**

| XHDB | Swift | WCDB |
| ------------ | ----- | ---- |
| 1.X          | 5.X   | 2.0.4 |
####  1、CocoaPods导入

在你的 Podfile 文件中添加 XHNetworking：

```ruby
pod 'XHDB', :git => 'https://gitee.com/hamsterm/xhdb.git', :tag => '1.0.0'
```

然后运行 `pod install`。

在任何你想使用 XHDB 的文件中，使用 `import XHDB` 导入框架。

#### 2、使用

- ##### 模型绑定（Object-relational Mapping，简称 ORM），通过对 Swift 类或结构进行绑定，形成**类或结构 - 表模型**、**类或结构对象 - 表**的映射关系，从而达到通过对象直接操作数据库的目的。


WCDB Swift 的字段映射基于 [Swift 4.0 的 `Codable` 协议实现](https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types)。以下是一个字段映射的示例代码：

```swift
final public class XHDBSample: TableCodable {
    
    public var name: String?
    public var sex: Int?
    public var score: Int?
    public var uid: String?
    
    public enum CodingKeys: String, CodingTableKey {
        
        public typealias Root = XHDBSample
        public static let objectRelationalMapping = TableBinding(CodingKeys.self) {
            BindColumnConstraint(uid, isPrimary: true, isUnique: true)
        }
        
        case name
        case sex
        case score
        case uid = "id"
    }
}
```

`BindColumnConstraint` 初始化函数的声明如下：

```swift
BindColumnConstraint(
    isPrimary: Bool = false, // 该字段是否为主键。字段约束中只能同时存在一个主键
    orderBy term: OrderTerm? = nil, // 当该字段是主键时，存储顺序是升序还是降序
    isAutoIncrement: Bool = false, // 当该字段是主键时，其是否支持自增。只有整型数据可以定义为自增。
    onConflict conflict: Conflict? = nil, // 当该字段是主键时，若产生冲突，应如何处理
    isNotNull: Bool = false, // 该字段是否可以为空
    isUnique: Bool = false, // 该字段是否可以具有唯一性
    defaultTo defaultValue: ColumnDef.DefaultType? = nil // 该字段在数据库内使用什么默认值
)
```

- ##### 创建数据库表

```swift
XHDB.share.createTable(XHDBSampleDB.table.rawValue, type: XHDBSample.self)
```

- ##### 数据库操作

```swift
public enum XHDBSampleDB: String {
    
    case table = "SampleTable"
    
    /// 插入数据
    public func inset(objects: [XHDBSample]) {
        XHDB.share.insertOrReplace(objects: objects, tableName: self.rawValue)
    }
    
    /// 查询数据（按照score升序排序 && score>=90分）
    public func query() -> [XHDBSample]? {
        return XHDB.share.query(
            self.rawValue,
            where: XHDBSample.Properties.score >= 90,
            orderBy: [XHDBSample.Properties.score.order(.ascending)])
    }
    
    /// 查询成绩最高的人
    public func queryMaxScore() -> XHDBSample? {
        return XHDB.share.query(
            self.rawValue,
            orderBy: [XHDBSample.Properties.score.order(.descending)],
            limit: 1)?.first
    }
    
    /// 删除学生
    public func delete(uid: String) {
        XHDB.share.delete(self.rawValue, where: XHDBSample.Properties.uid == uid)
    }
        
    /// 清空表
    public func clear() {
        XHDB.share.delete(self.rawValue)
    }
  
}
```

- ##### 数据库升级

纵观上述字段映射、字段约束、索引和表约束等四个部分，都是通过调用 `create(table:of:)` 接口使其生效的。 实际上，该接口会将 模型绑定的定义 与 表本身的结构 联系起来，并进行更新。

对于字段映射：

1. 表已存在但模型绑定中未定义的字段，会被忽略。这可以用于删除字段。
2. 表不存在但模型绑定中有定义的字段，会被新增到表中。这可以用于新增字段。
3. 对于需要重命名的字段，可以通过别名的方式重新映射。

> 忽略字段并不会删除字段。对于该字段旧内容，会持续存在在表中，因此文件不会因此变小。实际上，数据库作为持续增长的二进制文件，只有将其数据导出生成另一个新的数据库，才有可能回收这个字段占用的空间。对于新插入的数据，该字段内容为空，不会对性能产生可见的影响。