grdb
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.
- Installs
- 163
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/johnrogers/claude-swift-engineering --skill grdb- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads grdb automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
GRDB
Direct SQLite access using 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 | Setting up DatabaseQueue or DatabasePool |
| Queries | Writing raw SQL, Record types, type-safe queries |
| Value Observation | Reactive queries, SwiftUI integration |
| Migrations | DatabaseMigrator, schema evolution |
| Performance | 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
- Choose DatabaseQueue (single connection) or DatabasePool (concurrent reads)
- Define migrations with DatabaseMigrator
- Create Record types (Codable, FetchableRecord, PersistableRecord)
- Write queries with raw SQL or QueryInterface
- Use ValueObservation for reactive updates
Requirements
- iOS 13+, macOS 10.15+
- Swift 5.7+
- GRDB.swift 6.0+
Common Mistakes
-
Performance assumptions without EXPLAIN PLAN — Assuming your query is fast or slow without checking
EXPLAIN QUERY PLANis guessing. Always profile queries with EXPLAIN before optimizing. -
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.
-
Improper migration ordering — Running migrations out of order or skipping intermediate versions breaks schema consistency. Always apply migrations sequentially; never jump versions.
-
Record conformance shortcuts — Not conforming Record types to
PersistableRecordorFetchableRecordcorrectly leads to silent data loss or deserialization failures. Always implement all required protocols correctly. -
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.
FAQ
What does the grdb skill do?
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.
How do I install grdb?
Run npx skills add https://github.com/johnrogers/claude-swift-engineering --skill grdb in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/grdb/ (personal) or .claude/skills/grdb/ (project).
Which AI agents can use grdb?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is grdb safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains grdb?
It is published by johnrogers in johnrogers/claude-swift-engineering. It has 163 recorded installs.
More from johnrogers/claude-swift-engineering
swift-style
johnrogers/claude-swift-engineering
Swift code style conventions for clean, readable code. Use when writing Swift code to ensure consistent formatting, naming, organization, and idiomatic patterns.
ios-hig
johnrogers/claude-swift-engineering
Open the skill to read its SKILL.md instructions.
swiftui-patterns
johnrogers/claude-swift-engineering
Open the skill to read its SKILL.md instructions.
ios-26-platform
johnrogers/claude-swift-engineering
Open the skill to read its SKILL.md instructions.
composable-architecture
johnrogers/claude-swift-engineering
Open the skill to read its SKILL.md instructions.
swift-testing
johnrogers/claude-swift-engineering
Use when writing tests with Swift Testing (@Test,
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.