Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering
Open on GitHub

What 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-engineering

This installs the whole swift-engineering plugin with all its skills

2Skills CLI (Vercel)

npx skills add johnrogers/claude-swift-engineering --skill grdb -a claude-code

3Manually: put the files in place

~/.claude/skills/grdb/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/grdb/

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

Similar skills

All skills for Mobile →

From the same set33

The whole set →
reflect reflect is a Claude Code command that reviews chat context and project settings, then suggests changes to instructions, commands, and configuration. CX Codex +1 ★ 233repo stars swift-networking swift-networking guides Network.framework implementation in Swift, handling low-level TCP and UDP traffic, concurrency queues, and connection state transitions. CX Codex +1 ★ 233repo stars ios-hig ios-hig is a Claude Code skill that applies Apple's iOS interface guidance to accessibility, visual design, and interaction. It supports screen creation and control review. CX Codex +1 ★ 233repo stars swift-engineer swift-engineer — a Claude subagent that writes vanilla Swift for models, services, networking and persistence when the plan rules out TCA. CX Codex ★ 233repo stars swift-diagnostics The swift-diagnostics skill guides investigations into navigation, build, and memory issues in iOS and macOS projects. Use it to follow diagnostic checks before changing code. CX Codex +1 ★ 233repo stars localization Walks the agent through iOS localization: String Catalogs, plural forms, locale-aware formats and right-to-left layout. CX Codex +1 ★ 233repo stars swiftui-advanced swiftui-advanced — a Claude Code skill providing advanced SwiftUI workflows for multi-gesture composition, layout adaptation, architecture choice, and profiling. CX Codex +1 ★ 233repo stars haptics Add tactile responses for confirmations, errors, and custom patterns in an iOS app. The skill helps choose between UIKit feedback generators and Core Haptics. CX Codex +1 ★ 233repo stars

Project sponsors

Companies that keep this analytics open