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.
When & Why to Use This Skill
This Claude skill provides expert-level assistance for GRDB.swift, a powerful toolkit for SQLite database management in iOS and macOS environments. It enables developers to write type-safe queries, handle complex multi-table joins, and implement reactive data observation while maintaining high performance and schema consistency through structured migrations.
Use Cases
- Advanced Query Authoring: Writing raw SQL for complex operations such as window functions (ROW_NUMBER, RANK) and joins involving 4 or more tables where standard ORMs are insufficient.
- Reactive UI Integration: Implementing real-time data synchronization in SwiftUI or UIKit apps using ValueObservation to automatically update interfaces when database content changes.
- Database Schema Evolution: Designing and managing sequential database migrations using DatabaseMigrator to ensure safe and consistent schema updates across app versions.
- Performance Tuning: Optimizing database interactions by analyzing EXPLAIN QUERY PLAN output, implementing strategic indexing, and choosing between DatabaseQueue and DatabasePool for concurrency.
- Type-Safe Data Mapping: Creating robust Record types using Codable, FetchableRecord, and PersistableRecord protocols to prevent runtime deserialization errors and data loss.
| 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 - type-safe Swift wrapper with full SQLite power when you need it.
Quick Reference
| 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.