grdb — Claude Code skill: what it does, how to install
Guides Claude Code in writing direct SQLite queries, schema migrations, and reactive observations with GRDB.swift on iOS and macOS.
MIT ★ 233 updated 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringWhat grdb does
This skill supplies engineering guidelines and reference files for integrating GRDB.swift into Apple ecosystem apps. It steps in when abstractions like SQLiteData hit their limits, specifically for joins across four or more tables, raw SQL queries, window functions like ROW_NUMBER, and reactive data streams using ValueObservation.
The skill organizes context around core database tasks: configuring DatabaseQueue or concurrent DatabasePool connections, defining schema changes with DatabaseMigrator, conforming types to FetchableRecord and PersistableRecord, and inspecting performance via EXPLAIN QUERY PLAN.
Optimizing queries without EXPLAIN QUERY PLAN is treated as guesswork, so the instructions demand profiling before adding indexes. Using this skill requires Swift 5.7+, GRDB.swift 6.0 or newer, and deployment targets of at least iOS 13 or macOS 10.15.
What it helps with
- write raw SQL queries joining four or more tables
- implement SQLite window functions like ROW_NUMBER and RANK in Swift
- set up reactive SwiftUI data pipelines using ValueObservation
- structure sequential schema migrations with DatabaseMigrator
- diagnose missing indexes and scan overhead with EXPLAIN QUERY PLAN
Example prompts for the agent
- Configure a DatabasePool and create a migration adding indices to orders
- Write a multi-table join with window ranking functions using GRDB QueryInterface
- Set up a ValueObservation stream for real-time task list updates in SwiftUI
How to install grdb
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 grdb -a claude-code3Manually: put the files in place
~/.claude/skills/grdb/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/grdb/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill grdb -a codex2Manually: put the files in place
.agents/skills/grdb/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill grdb -a cursor2Manually: put the files in place
.cursor/skills/grdb/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/grdb2Manually: put the files in place
.github/skills/grdb/SKILL.md1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill grdb -a gemini-cli2Platform CLI
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/grdbManually: put the files in place
.devin/skills/grdb/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 grdb
How to install grdb in Claude Code?
Add the repository marketplace using /plugin marketplace add johnrogers/claude-swift-engineering, then run /plugin install swift-engineering@claude-swift-engineering.
When should I use GRDB over SQLiteData?
Choose GRDB when you need window functions, raw SQL for performance bottlenecks, joins involving four or more tables, or ValueObservation. Stick with SQLiteData for standard @Table models and CloudKit syncing.
What versions of Swift and OS are required?
You need Swift 5.7+ and GRDB.swift 6.0+. The minimum OS targets specified in the skill are iOS 13 and macOS 10.15.
Source text
SKILL.md · MIT
--- name: grdb description: Use when writing raw SQL with GRDB, complex joins across 4+ tables, window functions, ValueObservation for reactive queries, or dropping down from SQLiteData for performance. Direct SQLite access for iOS/macOS with type-safe queries and migrations. --- # GRDB Direct SQLite access using [GRDB.swift](https://github.com/groue/GRDB.swift) - type-safe Swift wrapper with full SQLite power when you need it. ## 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 | |-----------|-----------| | **[Getting Started](references/getting-started.md)** | Setting up DatabaseQueue or DatabasePool | | **[Queries](references/queries.md)** | Writing raw SQL, Record types, type-safe queries | | **[Value Observation](references/value-observation.md)** | Reactive queries, SwiftUI integration | | **[Migrations](references/migrations.md)** | DatabaseMigrator, schema evolution | | **[Performance](references/performance.md)** | EXPLAIN QUERY PLAN, indexing, profiling | ## When to Use GRDB vs SQLiteData | Scenario | Use | |----------|-----| | Type-safe @Table models | SQLiteData | | CloudKit sync needed | SQLiteData | | Complex joins (4+ tables) | GRDB | | Window functions (ROW_NUMBER, RANK) | GRDB | | Performance-critical raw SQL | GRDB | | Reactive queries (ValueObservation) | GRDB | ## Core Workflow 1. Choose DatabaseQueue (single connection) or DatabasePool (concurrent reads) 2. Define migrations with DatabaseMigrator 3. Create Record types (Codable, FetchableRecord, PersistableRecord) 4. Write queries with raw SQL or QueryInterface 5. Use ValueObservation for reactive updates ## Requirements - iOS 13+, macOS 10.15+ - Swift 5.7+ - GRDB.swift 6.0+ ## Common Mistakes 1. **Performance assumptions without EXPLAIN PLAN** — Assuming your query is fast or slow without checking `EXPLAIN QUERY PLAN` is guessing. Always profile queries with EXPLAIN before optimizing. 2. **Missing indexes on WHERE clauses** — Queries filtering on non-indexed columns scan the entire table. Index any column used in WHERE, JOIN, or ORDER BY clauses for large tables. 3. **Improper migration ordering** — Running migrations out of order or skipping intermediate versions breaks schema consistency. Always apply migrations sequentially; never jump versions. 4. **Record conformance shortcuts** — Not conforming Record types to `PersistableRecord` or `FetchableRecord` correctly leads to silent data loss or deserialization failures. Always implement all required protocols correctly. 5. **ValueObservation without proper cleanup** — Forgetting to cancel ValueObservation when views disappear causes memory leaks and stale data subscriptions. Store the cancellable and clean up in deinit.
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering