sqlite-data

SQLite Data

SQLiteData 通过 Swift 宏提供类型安全的 SQLite 访问，简化数据库建模和查询，同时自动处理 CloudKit 同步、迁移和异步模式。

参考资料加载指南

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

参考资料	何时加载
表模型	使用 @Table 定义表、设置主键、列或枚举时
查询 - 基础	使用 @FetchAll、@FetchOne、@Selection、筛选、排序或连接时
查询 - 高级	使用 FetchKeyRequest 搭配 @Fetch、动态查询、递归 CTE 或直接读取时
写入	插入、更新、插入或更新记录、删除记录或管理事务时
视图 - SwiftUI	在 SwiftUI 视图中使用 @FetchAll/@FetchOne、@Observable 模型或动画时
视图 - 集成	集成 UIKit、动态加载查询、集成 TCA 或使用 observe {} 时
迁移	使用 DatabaseMigrator 或 #sql() 宏创建数据库迁移时
CloudKit 同步	设置 CloudKit 私有数据库同步、共享或同步代理时
依赖项	通过 @Dependency 注入数据库/同步引擎、设置引导模式或集成 TCA 时
测试	设置测试数据库、填充数据或为 SQLite 代码编写断言时
高级 - 查询	实现触发器、自定义数据库函数或全文搜索（FTS5）时
高级 - 优化	调优性能、使用索引、自定义聚合、JSON 聚合或自连接时
架构组合	使用 @Selection 列组、单表继承或数据库视图时

核心工作流

使用 SQLiteData 时：

1. 使用 @Table 宏定义表模型
2. 在视图或 @Observable 模型中使用 @FetchAll/@FetchOne 属性包装器
3. 通过 @Dependency(\.defaultDatabase) 访问数据库
4. 在 database.write { } 事务中执行写入
5. 首次使用前设置迁移

常见错误

1. N+1 查询模式 — 在循环中逐条加载记录（例如，先获取用户，再单独获取该用户的所有帖子）会严重影响性能。请改用连接或批量获取。

2. 架构变更时缺少迁移 — 修改 @Table 却不创建迁移，会导致运行时崩溃。部署前，务必为架构变更创建迁移。

3. 事务处理不当 — 在 database.write { } 代码块之外运行耗时事务，可能导致死锁或数据丢失。请保持写入代码块简短且专注。

4. 忽略 CloudKit 同步代理 — 设置 CloudKit 同步却不实现 SyncDelegate，意味着你将无法处理错误和解决冲突。生产环境中请实现所有代理方法。

5. 在 SwiftUI 视图中过度获取 — 使用 @FetchAll 却不筛选或限制，可能会加载数千条记录，导致界面卡顿。请使用谓词、限制和排序，以减少内存占用。