majiayu000 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.
Overview
Quick Reference
| Reference | Load When |
|---|---|
| Table Models | Defining database tables with @Table macro, setting up primary keys, columns, or enums |
| Queries | Using @FetchAll, @FetchOne, @Fetch property wrappers, or building queries with joins/filters |
| Writes | Inserting, updating, upserting, or deleting records; managing transactions |
| Views | Integrating @FetchAll/@FetchOne with SwiftUI views, @Observable models, UIKit, or TCA @ObservableState |
| 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 | Implementing triggers, full-text search (FTS5), or custom database functions |
| Schema Composition | Using @Selection column groups, single-table inheritance, or database views |
Core Workflow
When working with SQLiteData:
- Define table models with
@Tablemacro - Use
@FetchAll/@FetchOneproperty wrappers in views or@Observablemodels - Access database via
@Dependency(\.defaultDatabase) - Perform writes in
database.write { }transactions - Set up migrations before first use
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
@Tablewithout 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
SyncDelegatemeans you miss error handling and conflict resolution. Implement all delegate methods for production.Over-fetching in SwiftUI views — Using
@FetchAllwithout filtering/limiting can load thousands of records, freezing the UI. Use predicates, limits, and sorting to keep in-memory footprint small.