sqlite-data — Claude Code skill: what it does, how to install
Guides database modeling in Swift with the SQLiteData library, macro queries, migrations, and private CloudKit database sync.
MIT ★ 233 updated 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringWhat sqlite-data does
This skill guides Claude Code through developing with the Swift SQLiteData package. It provides patterns for declaring schemas via @Table, running queries with @FetchAll or @FetchOne, and structuring writes inside database.write transactions using @Dependency(\.defaultDatabase).
It includes references covering SwiftUI views, UIKit, and The Composable Architecture. The skill covers schema changes with DatabaseMigrator, advanced queries with recursive CTEs, FTS5 full-text search, and test database seeding.
Changing a @Table definition without an accompanying migration crashes the app at launch. The skill prevents this failure mode while flagging N+1 queries, unconstrained UI fetches, and missing SyncDelegate handlers during CloudKit setup.
What it helps with
- define SQLite table models using the
@Tablemacro - bind reactive queries to SwiftUI views via
@FetchAlland@FetchOne - manage write operations and avoid deadlocks in database transactions
- write versioned schema migrations with
DatabaseMigratoror#sql() - integrate private database syncing and delegates with CloudKit
Example prompts for the agent
- Create a note model using the
@Tablemacro with id, title, and timestamp columns - Write a filtered query using
@FetchAllfor an Observable SwiftUI view model - Set up a
DatabaseMigratorstep to add a new column to the existing schema
How to install sqlite-data
1Plugin marketplace
/plugin marketplace add johnrogers/claude-swift-engineering/plugin install swift-engineering@claude-swift-engineeringThis installs the whole swift-engineering plugin with all its skills
2Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill sqlite-data -a claude-code3Manually: put the files in place
~/.claude/skills/sqlite-data/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/sqlite-data/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill sqlite-data -a codex2Manually: put the files in place
.agents/skills/sqlite-data/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill sqlite-data -a cursor2Manually: put the files in place
.cursor/skills/sqlite-data/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/sqlite-data2Manually: put the files in place
.github/skills/sqlite-data/SKILL.md1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill sqlite-data -a gemini-cli2Platform CLI
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/sqlite-dataManually: put the files in place
.devin/skills/sqlite-data/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about sqlite-data
How to install sqlite-data in Claude Code?
Add the repository and install the plugin by running /plugin marketplace add johnrogers/claude-swift-engineering followed by /plugin install swift-engineering@claude-swift-engineering.
What is the sqlite-data skill used for?
It provides Claude Code with reference guides and rules for building persistence layers in Swift using the SQLiteData macro library.
Why does the skill require implementing SyncDelegate for CloudKit?
Setting up CloudKit sync without SyncDelegate drops error handling routines and breaks conflict resolution during record synchronisation.
Source text
SKILL.md · MIT
---
name: sqlite-data
description: Use when working with SQLiteData library (@Table, @FetchAll, @FetchOne macros) for SQLite persistence, queries, writes, migrations, or CloudKit private database sync.
---
# 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.
## 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](references/models.md)** | Defining tables with `@Table`, setting up primary keys, columns, or enums |
| **[Queries - Basics](references/queries-basics.md)** | Using `@FetchAll`, `@FetchOne`, `@Selection`, filtering, ordering, or joins |
| **[Queries - Advanced](references/queries-advanced.md)** | Using `@Fetch` with `FetchKeyRequest`, dynamic queries, recursive CTEs, or direct reads |
| **[Writes](references/writes.md)** | Inserting, updating, upserting, deleting records, or managing transactions |
| **[Views - SwiftUI](references/views-swiftui.md)** | Using `@FetchAll`/`@FetchOne` in SwiftUI views, `@Observable` models, or animations |
| **[Views - Integration](references/views-integration.md)** | UIKit integration, dynamic query loading, TCA integration, or `observe {}` |
| **[Migrations](references/migrations.md)** | Creating database migrations with `DatabaseMigrator` or `#sql()` macro |
| **[CloudKit Sync](references/cloudkit.md)** | Setting up CloudKit private database sync, sharing, or sync delegates |
| **[Dependencies](references/dependencies.md)** | Injecting database/sync engine via `@Dependency`, bootstrap patterns, or TCA integration |
| **[Testing](references/testing.md)** | Setting up test databases, seeding data, or writing assertions for SQLite code |
| **[Advanced - Queries](references/advanced-queries.md)** | Implementing triggers, custom database functions, or full-text search (FTS5) |
| **[Advanced - Optimization](references/advanced-optimization.md)** | Performance tuning, indexes, custom aggregates, JSON aggregation, or self-joins |
| **[Schema Composition](references/schema-composition.md)** | Using `@Selection` column groups, single-table inheritance, or database views |
## Core Workflow
When working with SQLiteData:
1. Define table models with `@Table` macro
2. Use `@FetchAll`/`@FetchOne` property wrappers in views or `@Observable` models
3. Access database via `@Dependency(\.defaultDatabase)`
4. Perform writes in `database.write { }` transactions
5. Set up migrations before first use
## Common Mistakes
1. **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.
2. **Missing migrations on schema changes** — Modifying `@Table` without creating a migration causes crashes at runtime. Always create migrations for schema changes before deploying.
3. **Improper transaction handling** — Long-running transactions outside of `database.write { }` block can cause deadlocks or data loss. Keep write blocks short and focused.
4. **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.
5. **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.
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering