SQLiteData 是 Point-Free 开发的类型安全 SQLite 持久化库（pointfreeco/sqlite-data），定位为 SwiftData 的快速、轻量替代方案，并支持 CloudKit 同步。它构建在 GRDB（groue/GRDB.swift）与 StructuredQueries（pointfreeco/swift-structured-queries）之上。核心原则是：值类型（struct）+ @Table 宏 + 所有变更通过 database.write { } 块执行。
用途与适用场景
当需要类型安全 SQLite 与编译器检查的查询、CloudKit 同步与记录共享、5 万条以上记录且接近原生 SQLite 性能的大数据集、使用值类型（struct）而非类、以及 Swift 6 严格并发支持时，可选择 SQLiteData。若只需简单 CRUD 与 Apple 原生集成、偏好 @Model 类而非 struct、不需要 CloudKit 记录共享，则应改用 SwiftData。若需要跨 4 张以上表的复杂 SQL 连接、超出模式变更的自定义迁移逻辑、或需要手写 SQL 的性能关键操作，则应直接使用原始 GRDB。
主要能力
模型定义：使用 @Table 宏标注 nonisolated struct，第一个 let 属性自动成为主键；默认值（= ""、= true）表示非空列，可选属性（String?）映射为可空列。支持自定义主键（@Column(primaryKey: true)）、列自定义表示（@Column(as:)）、显式外键列（关系通过连接表达，而非 @Relationship 宏）、以及 @Ephemeral 标记不持久化的属性（必须提供默认值）。
查询：支持 @FetchAll、@FetchOne 属性包装器在 SwiftUI 中观察数据库变化，自动订阅变更、主线程运行、视图消失时取消观察（iOS 17+）。支持 keypath 简单过滤、闭包复杂过滤、contains/hasPrefix/suffix、单列与多列排序、limit/offset 分页。v1.4.0+ 提供静态辅助方法 Item.fetchAll(db)、Item.find(db, key:)（返回非可选值），以及 .task 生命周期感知获取以自动取消观察。还支持 #sql 宏编写类型安全的原始 SQL。
增删改：插入使用静态 Item.insert { Item.Draft(...) }.execute(db)，可配合 .returning(.id) 获取生成的 ID；更新支持单条（Item.find(id).update { ... }）与批量（Item.where(...).update { ... }）；删除支持单条与批量。支持 UPSERT（INSERT ... ON CONFLICT ... DO UPDATE），可指定冲突目标列、部分唯一索引的冲突过滤条件，以及多种合并策略（全量替换、不覆盖合并、最后写入胜出）。
批量操作：支持批量插入（values 块传入数组）。
CloudKit 同步：通过 SyncEngine 配置（v1.2-1.4+），支持手动同步控制 fetchChanges()、sendChanges()、syncChanges()，以及同步状态观察 isSendingChanges、isFetchingChanges、isSynchronizing。
数据库设置：使用 GRDB 的 DatabaseQueue 与 DatabaseMigrator 注册迁移，通过 Dependencies 注册 defaultDatabase，在应用初始化时 prepareDependencies。
常见反模式
在谓词中使用 ==（StructuredQueries 0.31+ 已移除，应使用 .eq(#bind(...)) 等比较方法）；更新赋值缺少 #bind（复合运算符 +=、-= 无需 #bind）；更新顺序错误（.update 应在 .where 之后，单条用 .find()）；对实例调用 insert（应使用静态 insert 配合 .Draft）；缺少 nonisolated（Swift 6 并发警告）；在 write 块内使用 await（write 块是同步的）；忘记 .execute(db)（查询构建但不会执行）。
限制与要求
要求 iOS 17+ 与 Swift 6 严格并发。采用 MIT 许可。跨 4 张以上表的复杂连接需回退到原始 GRDB。SQLiteData 使用显式外键列，关系通过连接表达。@Ephemeral 属性必须有默认值。UPSERT 需要匹配的 UNIQUE 约束或索引，不应使用 INSERT OR REPLACE（会先删除再插入，破坏外键关系）。
高级模式（CTE、视图、自定义聚合、模式组合）可参考 axiom-sqlitedata-ref 参考技能。