本文主要介绍 WCDB Swift 的三个基础类：数据库 - Database、表 - Table 和 事务 - Transaction。它们同时拥有以下特性：

• 支持增删查改的便捷接口
• 支持链式接口
• 数据和状态共享
• 线程安全
  数据和状态共享，意味着对于 同一个路径的数据库 的 不同基础类，它们的标签、数据库是否打开、是否在进行读写操作等所有状态和数据都始终保持一致。

let myTag = 1
let database = Database(withPath: filePath)
database.tag = myTag
print(database.tag) // 输出 1
 
let databaseAlias = Database(withPath: filePath)
print(databaseAlias.tag) // 输出 1
 
let table = try database.getTable(named: "sampleTable", of: Sample.self)
print(table.tag) // 输出 1
 
let transaction = try database.getTransaction()
print(transaction.tag) // 输出 1
 
database.tag = 2
print(database.tag) // 输出 2
print(databaseAlias.tag) // 输出 2
print(table.tag) // 输出 2
print(transaction.tag) // 输出 2

基础类共享数据和状态的本质是，它们共享同一个 Core，而所有操作都在这个 Core 上发生。

线程安全，意味着开发者可以在 任意线程 对 任意基础类 调用 任意接口，而不需要考虑数据库本身的线程安全问题。同时，WCDB Swift 会根据调用情况，并发执行操作，以达到更高的性能。

WCDB Swift 支持 多线程读操作 或 单线程写多线程读 并发执行。

数据库

Database 是 WCDB Swift 中最基础的类，几乎所有操作都由该类发起。

初始化

Database 可以通过文件路径或文件 URL 创建一个数据库。

let filePath = "~/Intermediate/Directories/Will/Be/Created/sample.db"
let databaseWithPath = Database(withPath: filePath)
 
let fileURL = URL(fileURLWithPath: filePath)
let databaseWithFileURL = Database(withFileURL: fileURL)

对于已经存在的数据库，也可以通过 tag 来获取。

let myTag = 1
databaseWithPath.tag = myTag
 
// 若该 tag 不存在，则初始化会失败
let databaseWithTag = try Database(withExistingTag: myTag)

标签

通过设置标签，可以区分不同的数据库。

let myTag1 = 1
let database1 = Database(withPath: path1)
database1.tag = myTag1
 
let myTag2 = 2
let database2 = Database(withPath: path2)
database2.tag = myTag2

同时，基于基础类数据共享的机制，对于同一路径的基础类，它们会共享同一个 tag。

print(database1.tag) // 输出 1
 
let anotherDatabase1 = Database(withPath: path1)
print(anotherDatabase1.tag) // 输出 1

打开数据库

延迟初始化是 WCDB Swift 的原则之一，绝大部分数据只会在需要用到时才创建并初始化。数据库的打开就是其中一个例子。

数据库会在第一次进行操作时，自动打开并初始化。开发者不需要手动调用。

let database = Database(withPath: filePath)
print(database.isOpened) // 输出 false
try database.create(table: "sampleTable", of: Sample.self) // 数据库此时会被自动打开
print(database.isOpened) // 输出 true

同时，也可以通过 canOpen 接口测试数据库能否正常打开。

let database1 = Database(withPath: filePath)
print(database1.isOpened) // 输出 false
print(database1.canOpen) // 输出 true。仅当数据库无法打开时，如路径无法创建等，该接口会返回 false
print(database1.isOpened) // 输出 true
let database2 = Database(withPath: filePath)
print(database2.isOpened) // 输出 true。WCDB Swift 同一路径的数据库共享数据和状态等。

关闭数据库

与打开数据库相对应，关闭数据库一般情况下也不需要开发者手动调用。当没有指向 Database 所共享的 Core 时，数据库会自动关闭，并回收内存。

do {
    let database1 = Database(withPath: filePath)
    try database1.create(table: "sampleTable", of: Sample.self) // 数据库此时会被自动打开
    print(database1.isOpened) // 输出 true
} // 作用域结束，database1 deinit、关闭数据库并回收内存
let database2 = Database(withPath: filePath)
print(database2.isOpened) // 输出 false

let database1 = Database(withPath: filePath)
{
    let database2 = Database(withPath: filePath)
    try database2.create(table: "sampleTable", of: Sample.self) // 数据库此时会被自动打开
    print(database2.isOpened) // 输出 true
} // 作用域结束，database2 deinit，但 database1 仍持有该路径的数据库，因此不会被关闭。
print(database1.isOpened) // 输出 true

同时，也可以调用 close 接口，手动关闭数据库。

let database = Database(withPath: filePath)
print(database.canOpen) // 输出 true
print(database.isOpened) // 输出 true
database.close()
print(database.isOpened) // 输出 false

WCDB Swift 也提供了 blockade、unblockade 和 isBlockaded 接口用于分步执行关闭数据库操作，可参考相关接口文档

关闭数据库与线程安全

某些情况下，开发者需要确保数据库完全关闭后才能进行操作，如移动文件操作。

数据库是二进制文件，移动文件的过程中若数据发生了变化，则移动后的文件数据可能会不完整、损坏。因此，WCDB Swift 提供了 close: 接口。

try database.close(onClosed: {
    try database.moveFiles(toDirectory: otherDirectory)
})

在 onClosed 参数内，可确保数据库完全关闭，不会有其他线程的数据访问、操作数据库，因此可以安全地操作文件。

内存回收

purge 接口用于回收暂不使用的内存。

// 回收 database 数据库中暂不使用的内存
database.purge() 
// 回收所有已创建的数据库中暂不使用的内存
Database.purge() 

在 iOS 平台上，当内存不足、收到系统警告时，WCDB Swift 会自动调用 Database.purge() 接口以减少内存占用。

文件操作

// 获取所有与该数据库相关的文件路径
print(database.paths) 
// 获取所有与该数据库相关的文件占用的大小
try database.close(onClosed: {
    // 数据库未关闭状态下也可获取文件大小，但不够准确，开发者可自行选择是否关闭
    let filesSize = try database.getFilesSize()
    print(filesSize)
})
// 删除所有与该数据库相关的文件
try database.close(onClosed: {
    try database.removeFiles()
})
// 将所有与该数据库相关的文件移动到另一个目录
try database.close(onClosed: {
    try database.moveFiles(toDirectory: otherDirectory)
})

表

Table 指代数据库中的一个表。可以通过 getTable 接口获取。

let table = try database.getTable(named: "sampleTable", of: Sample.self) //  表不存在时会出错

表相当于指定了表名和模型绑定类的 Database，其实质只是后者的简化版。

// 返回值需指定为 [Sample] 类型以匹配范型
let objectsFromDatabase: [Sample] = try database.getObjects(fromTable: "sampleTable")
 
// table 已经指定了表名和模型绑定的类，因此可以直接获取
let objectsFromTable = try table.getObjects()

事务

事务一般用于 提升性能 和 保证数据原子性。Database 和 Table 都能直接发起事务，也可以通过 Transaction 更好地控制事务。

try database.run(transaction: {
    try database.insert(objects: object, intoTable: "sampleTable")
})
 
let table = try database.getTable(named: "sampleTable", of: Sample.self)
table.run(transaction: {
    try database.insert(objects: object)
})
 
// 与 Database、Table 类似，开发者可以保存 Transaction 变量
let transaction = try database.getTransaction()
transacton.run(transaction: {
    print(transaction.isInTransction) // 输出 true
    try transaction.insert(objects: object)
})

性能

事务提升性能的实质是批量处理。

let object = Sample()
object.isAutoIncrement = true
let objects = Array(repeating: object, count: 100000)
 
// 单独插入，效率很差
for object in objects {
    try database.insert(objects: object, intoTable: "sampleTable")
}
 
// 事务插入，性能较好
try database.run(transaction: {
    for object in objects {
        try database.insert(objects: object, intoTable: "sampleTable")
    }
})
 
// insert(objects:intoTable:) 接口内置了事务，并对批量数据做了针对性的优化，性能更好
try database.insert(objects: objects, intoTable: "sampleTable")

原子性

试考虑以下代码：

DispatchQueue(label: "other thread").async {
    try database.delete(fromTable: "sampleTable")
}
 
try database.insert(object: object, intoTable: "sampleTable")
let objects = try database.getObjects(fromTable: "sampleTable")
print(objects.count) // 可能输出 0 或 1

在多线程下，删除操作发生的时机是不确定的。倘若它发生在 插入完成之后 和 取出数据之前 的瞬间，则 getObjects(fromTable:) 无法取出刚才插入的数据，且这种多线程低概率的 bug 是很难查的。

而事务可以保证一段操作的原子性：

DispatchQueue(label: "other thread").async {
    try database.delete(fromTable: "sampleTable")
}
 
try database.run(transaction: {
    try database.insert(objects: object, intoTable: "sampleTable")
    let objects = try database.getObjects(fromTable: "sampleTable")
    print(objects.count) // 输出 1
})

执行事务

WCDB Swift 提供了三种事务，普通事务、可控事务和嵌入事务。

// 普通事务
try database.run(transaction: {
    try database.insert(objects: object, intoTable: "sampleTable")
})
// 可控事务
try database.run(controllableTransaction: {
    try database.insert(objects: object, intoTable: "sampleTable")
    return true // 返回 true 以提交事务，返回 false 以回滚事务
})

可控事务在普通事务的基础上，可以通过返回值控制提交或回滚事务。

// 普通事务
try database.run(transaction: {
    try database.run(transaction: { // 出错，事务不能嵌套
        try database.insert(objects: object, intoTable: "sampleTable")
    })
})
// 嵌入事务
try database.run(transaction: {
    try database.run(embeddedTransaction: { // 嵌入事务可以嵌套
        try database.insert(objects: object, intoTable: "sampleTable")
    })
})

嵌入事务在普通事务的基础上，支持嵌套调用。

当外层不存在事务时，嵌入事务和普通事务没有区别。

当外层存在事务时，嵌入事务会跟随外层事务的行为提交或回滚事务。

insert(objects:intoTable:)、insertOrReplace(objects:intoTable:)、create(table:of:) 等 WCDB Swift 自带的接口都使用了嵌入事务

WCDB Swift 也提供了 begin、commit 和 rollback 接口用于分步执行事务，可参考相关接口文档