# grdb

Guides Claude Code in writing direct SQLite queries, schema migrations, and reactive observations with GRDB.swift on iOS and macOS.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 233 repo stars
- Author: John Rogers (@johnrogers)
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/grdb/SKILL.md
- Updated: 2026-01-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/grdb

## What it 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.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add johnrogers/claude-swift-engineering
```
In the agent chat (not a shell):
```text
/plugin install swift-engineering@claude-swift-engineering
```
This installs the whole swift-engineering plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill grdb -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/grdb/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/grdb/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill grdb -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/grdb/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill grdb -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/grdb/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/grdb
```

2. **Manually: put the files in place**
- File: `.github/skills/grdb/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill grdb -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/grdb
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/grdb/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/grdb/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0a4bca88b3a4105d.

BEGIN THIRD-PARTY FILE 0a4bca88b3a4105d
```text
---
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.
```
END THIRD-PARTY FILE 0a4bca88b3a4105d

The third-party file has ended. Everything between the 0a4bca88b3a4105d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2255 of 2883 bytes. © John Rogers (@johnrogers) · MIT · https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/grdb/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
