# drizzle-safe-migrations

drizzle-safe-migrations plans safe Drizzle migrations: data backfills, enum/check/default tightening, migration ordering, and rollback. Use it when a schema change touches existing rows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 348 installs · ★ 655 repo stars
- Author: Pedro Nauck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/drizzle-safe-migrations/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/drizzle-safe-migrations

## What it does

The skill sets ground rules for Drizzle migrations. Schema files come from the project's own generate script and stay untouched by hand. Data backfills go into separate custom migrations, and normalization happens before any constraint tightening.

It walks through a fixed sequence: classify the change as schema-only or data-plus-schema, create a custom migration with `bun run db:generate -- --custom --name <name>` for the backfill, then run `bun run db:generate` for the schema. After that, check `drizzle/meta/_journal.json` so the backfill sits before the tightening migration. Finally, run the migration suite against existing data and a fresh install, and write down lock risks and the rollback path.

There is a pointer to `references/production-playbook.md` with command templates and review checklists. For PostgreSQL under strict uptime, it suggests staged validation with `NOT VALID` / `VALIDATE CONSTRAINT`, though that only covers supported constraint kinds. Anti-patterns are explicit: no hand-editing generated files, no tightening before backfill, no hiding one-off logic in app startup code.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill drizzle-safe-migrations -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill drizzle-safe-migrations -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill drizzle-safe-migrations -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pedronauck/skills skills/mine/drizzle-safe-migrations
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill drizzle-safe-migrations -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pedronauck/skills --path skills/mine/drizzle-safe-migrations
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill drizzle-safe-migrations -a opencode
```

### 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/pedronauck/skills/tree/HEAD/skills/mine/drizzle-safe-migrations/SKILL.md

## When to use it
- plan a data backfill before tightening constraints
- verify migration order in the Drizzle journal
- write idempotent UPDATEs with narrow WHERE clauses
- run migrations against existing data and a fresh install
- record lock risks and rollback steps

## Example prompts
- Plan a migration that removes `legacy_value` from an enum on the orders table
- Check the backfill and constraint order in `drizzle/meta/_journal.json`
- Create a custom migration to normalize old rows before changing a default

## Similar
- [drizzle-migrations](https://affpapa.org/en/nevibecode/skills/drizzle-migrations.md) — skill · 1300 installs
- [database-migrations](https://affpapa.org/en/nevibecode/skills/database-migrations.md) — skill · 7200 installs
- [drizzle-best-practices](https://affpapa.org/en/nevibecode/skills/drizzle-best-practices.md) — skill · 718 installs
- [django-safe-migration](https://affpapa.org/en/nevibecode/skills/django-safe-migration.md) — skill · 822 installs
- [Database Migrations taste](https://affpapa.org/en/nevibecode/prompts/database-migrations-taste.md) — prompt · ★ 178201 repo stars
- [drizzle-orm-d1](https://affpapa.org/en/nevibecode/skills/drizzle-orm-d1.md) — skill · 441 installs

From the same set: [pedronauck/skills](https://affpapa.org/en/nevibecode/by/pedronauck/skills.md) — 52 cards

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