grdb

GRDB

使用 GRDB.swift 直接访问 SQLite——这是一个类型安全的 Swift 封装，在需要时可充分发挥 SQLite 的全部功能。

参考资料加载指南

只要有一点可能用到相关内容，就务必加载参考文件。 有上下文总比遗漏模式或犯错好。

参考资料	加载时机
入门指南	设置 DatabaseQueue 或 DatabasePool
查询	编写原始 SQL、Record 类型、类型安全查询
值观察	响应式查询、SwiftUI 集成
迁移	DatabaseMigrator、架构演进
性能	EXPLAIN QUERY PLAN、索引、性能分析

何时使用 GRDB 与 SQLiteData

场景	使用
类型安全的 @Table 模型	SQLiteData
需要 CloudKit 同步	SQLiteData
复杂联接（4 张以上表）	GRDB
窗口函数（ROW_NUMBER、RANK）	GRDB
对性能要求严格的原始 SQL	GRDB
响应式查询（ValueObservation）	GRDB

核心工作流

1. 选择 DatabaseQueue（单连接）或 DatabasePool（并发读取）
2. 使用 DatabaseMigrator 定义迁移
3. 创建 Record 类型（Codable、FetchableRecord、PersistableRecord）
4. 使用原始 SQL 或 QueryInterface 编写查询
5. 使用 ValueObservation 实现响应式更新

要求

• iOS 13+、macOS 10.15+
• Swift 5.7+
• GRDB.swift 6.0+

常见错误

1. 未使用 EXPLAIN PLAN 就假设性能 — 不检查 EXPLAIN QUERY PLAN 就假设查询速度快或慢，只是在猜测。优化前务必使用 EXPLAIN 分析查询性能。

2. WHERE 子句缺少索引 — 对未建立索引的列进行筛选时，查询会扫描整张表。对于大型表，WHERE、JOIN 或 ORDER BY 子句中使用的列都应建立索引。

3. 迁移顺序不当 — 乱序运行迁移或跳过中间版本会破坏架构一致性。务必按顺序依次应用迁移，切勿跳过版本。

4. Record 遵循协议时走捷径 — Record 类型未正确遵循 PersistableRecord 或 FetchableRecord，会导致数据悄然丢失或反序列化失败。务必正确实现所有必需的协议。

5. ValueObservation 未妥善清理 — 视图消失时忘记取消 ValueObservation，会导致内存泄漏和过期的数据订阅。请保存可取消对象，并在 deinit 中清理。