sqlite-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SQLite Data

SQLiteData provides type-safe SQLite access through Swift macros, simplifying database modeling and queries while handling CloudKit sync, migrations, and async patterns automatically.

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

Reference Loading Guide

参考文档加载指南

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

Reference	Load When
Table Models	Defining tables with `@Table` , setting up primary keys, columns, or enums
Queries - Basics	Using `@FetchAll` , `@FetchOne` , `@Selection` , filtering, ordering, or joins
Queries - Advanced	Using `@Fetch` with `FetchKeyRequest` , dynamic queries, recursive CTEs, or direct reads
Writes	Inserting, updating, upserting, deleting records, or managing transactions
Views - SwiftUI	Using `@FetchAll` / `@FetchOne` in SwiftUI views, `@Observable` models, or animations
Views - Integration	UIKit integration, dynamic query loading, TCA integration, or `observe {}`
Migrations	Creating database migrations with `DatabaseMigrator` or `#sql()` macro
CloudKit Sync	Setting up CloudKit private database sync, sharing, or sync delegates
Dependencies	Injecting database/sync engine via `@Dependency` , bootstrap patterns, or TCA integration
Testing	Setting up test databases, seeding data, or writing assertions for SQLite code
Advanced - Queries	Implementing triggers, custom database functions, or full-text search (FTS5)
Advanced - Optimization	Performance tuning, indexes, custom aggregates, JSON aggregation, or self-joins
Schema Composition	Using `@Selection` column groups, single-table inheritance, or database views

只要有极小概率需要用到相关内容，就务必加载参考文件。 拥有上下文总比遗漏模式或犯错要好。

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

Core Workflow

核心工作流

When working with SQLiteData:

Define table models with
```
@Table
```
macro
Use
```
@FetchAll
```
/
```
@FetchOne
```
property wrappers in views or
```
@Observable
```
models
Access database via
```
@Dependency(\.defaultDatabase)
```
Perform writes in
```
database.write { }
```
transactions
Set up migrations before first use

使用SQLiteData时的步骤：

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

Common Mistakes

常见错误

N+1 query patterns — Loading records one-by-one in a loop (e.g., fetching user then fetching all their posts separately) kills performance. Use joins or batch fetches instead.
Missing migrations on schema changes — Modifying
```
@Table
```
without creating a migration causes crashes at runtime. Always create migrations for schema changes before deploying.
Improper transaction handling — Long-running transactions outside of
```
database.write { }
```
block can cause deadlocks or data loss. Keep write blocks short and focused.
Ignoring CloudKit sync delegates — Setting up CloudKit sync without implementing
```
SyncDelegate
```
means you miss error handling and conflict resolution. Implement all delegate methods for production.
Over-fetching in SwiftUI views — Using
```
@FetchAll
```
without filtering/limiting can load thousands of records, freezing the UI. Use predicates, limits, and sorting to keep in-memory footprint small.

N+1查询模式 —— 在循环中逐个加载记录（例如先获取用户再单独获取其所有帖子）会严重影响性能。应改用关联查询或批量获取。
Schema变更时遗漏迁移 —— 修改
```
@Table
```
却未创建迁移会导致运行时崩溃。部署前务必为所有Schema变更创建迁移。
事务处理不当 —— 在
```
database.write { }
```
块外执行长时间运行的事务可能导致死锁或数据丢失。保持写入块简短且聚焦。
忽略CloudKit同步代理 —— 设置CloudKit同步却未实现
```
SyncDelegate
```
，会错过错误处理和冲突解决。生产环境中务必实现所有代理方法。
SwiftUI视图中过度获取数据 —— 使用
```
@FetchAll
```
却不进行过滤/限制可能加载数千条记录，导致UI冻结。请使用谓词、限制条件和排序来减少内存占用。