sqlite-data

SQLite Data

SQLiteData は Swift マクロを通じて型安全な SQLite アクセスを提供し、データベースのモデリングとクエリを簡素化するとともに、CloudKit 同期、マイグレーション、非同期パターンを自動的に処理します。

リファレンスの読み込みガイド

内容が必要になる可能性が少しでもある場合は、必ずリファレンスファイルを読み込んでください。 パターンを見落としたり、誤りを犯したりするより、必要なコンテキストを把握しておくほうが確実です。

リファレンス	読み込むタイミング
Table Models	@Table を使ったテーブルの定義、主キー、カラム、列挙型の設定を行う場合
Queries - Basics	@FetchAll、@FetchOne、@Selection、フィルタリング、並べ替え、結合を使用する場合
Queries - Advanced	FetchKeyRequest を使った @Fetch、動的クエリ、再帰的 CTE、直接読み込みを使用する場合
Writes	レコードの挿入、更新、アップサート、削除、トランザクションの管理を行う場合
Views - SwiftUI	SwiftUI ビューで @FetchAll／@FetchOne、@Observable モデル、アニメーションを使用する場合
Views - Integration	UIKit との統合、動的なクエリの読み込み、TCA との統合、observe {} を使用する場合
Migrations	DatabaseMigrator または #sql() マクロを使ってデータベースのマイグレーションを作成する場合
CloudKit Sync	CloudKit のプライベートデータベース同期、共有、同期デリゲートを設定する場合
Dependencies	@Dependency を使ったデータベース／同期エンジンの注入、ブートストラップパターン、TCA との統合を行う場合
Testing	テスト用データベースの設定、データのシード、SQLite コードのアサーション作成を行う場合
Advanced - Queries	トリガー、カスタムデータベース関数、全文検索（FTS5）を実装する場合
Advanced - Optimization	パフォーマンス調整、インデックス、カスタム集計、JSON 集計、自己結合を行う場合
Schema Composition	@Selection のカラムグループ、単一テーブル継承、データベースビューを使用する場合

基本的なワークフロー

SQLiteData を使用する場合：

1. @Table マクロでテーブルモデルを定義します
2. ビューまたは @Observable モデルで @FetchAll／@FetchOne プロパティラッパーを使用します
3. @Dependency(\.defaultDatabase) を通じてデータベースにアクセスします
4. database.write { } トランザクション内で書き込みを実行します
5. 初回使用前にマイグレーションを設定します

よくある間違い

1. N+1 クエリパターン — ループ内でレコードを1件ずつ読み込む（例：ユーザーを取得してから、そのユーザーの投稿をすべて別途取得する）と、パフォーマンスが大きく低下します。代わりに結合または一括取得を使用してください。

2. スキーマ変更時のマイグレーション漏れ — マイグレーションを作成せずに @Table を変更すると、実行時にクラッシュします。デプロイ前に、必ずスキーマ変更用のマイグレーションを作成してください。

3. 不適切なトランザクション処理 — database.write { } ブロックの外で長時間実行されるトランザクションは、デッドロックやデータ損失の原因になることがあります。書き込みブロックは短く、目的を絞ったものにしてください。

4. CloudKit 同期デリゲートの無視 — SyncDelegate を実装せずに CloudKit 同期を設定すると、エラー処理や競合解決が行われません。本番環境では、すべてのデリゲートメソッドを実装してください。

5. SwiftUI ビューでの過剰なデータ取得 — フィルタリングや件数制限をせずに @FetchAll を使うと、数千件のレコードが読み込まれ、UI がフリーズすることがあります。述語、件数制限、並べ替えを使用して、メモリ上の使用量を抑えてください。