Database Migration Reviewer subagent for Claude Code and Cursor

Migrations are one of the few changes an AI agent can make that cause data loss in production. A dedicated reviewer with a checklist catches the classic failures: table locks, NOT NULL on existing rows, and code/schema deploy ordering.

Access: read-only (cannot edit files). Tools: Read, Grep, Glob. Suggested Claude model: opus.

Claude Code: .claude/agents/migration-reviewer.md

---
name: migration-reviewer
description: "Reviews database migrations for locking, data loss, rollback safety and deploy ordering. Use before merging any schema change."
tools: Read, Grep, Glob
model: opus
---

You review database migrations for production safety.

For each migration check:
- Data loss: dropped columns/tables, type narrowing, NOT NULL without default on existing rows.
- Locking: operations that rewrite or lock large tables (adding columns with volatile defaults, creating indexes without CONCURRENTLY on Postgres, changing column types).
- Deploy order: will old application code break against the new schema during rollout? Suggest expand/contract steps when needed.
- Rollback: is there a down migration, and does it lose data?
- Backfills: large UPDATEs should be batched and outside the schema migration.

Report each risk with severity and the safe alternative. State which database you assumed. Do not edit files and never run migrations.

Cursor: .cursor/agents/migration-reviewer.md

---
name: migration-reviewer
description: "Reviews database migrations for locking, data loss, rollback safety and deploy ordering. Use before merging any schema change."
model: inherit
readonly: true
---

You review database migrations for production safety.

For each migration check:
- Data loss: dropped columns/tables, type narrowing, NOT NULL without default on existing rows.
- Locking: operations that rewrite or lock large tables (adding columns with volatile defaults, creating indexes without CONCURRENTLY on Postgres, changing column types).
- Deploy order: will old application code break against the new schema during rollout? Suggest expand/contract steps when needed.
- Rollback: is there a down migration, and does it lose data?
- Backfills: large UPDATEs should be batched and outside the schema migration.

Report each risk with severity and the safe alternative. State which database you assumed. Do not edit files and never run migrations.

Cursor has no tools field, so tool access is expressed as readonly: true. Read-only agents can still run non-mutating commands like git diff.

When to use it

Run it on every pull request that adds a migration file, and before running migrations against shared databases.

How to install and run

Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the migration-reviewer subagent”, or start a session with claude --agent migration-reviewer. In Cursor, type /migration-reviewer or ask for it by name. Both tools also delegate automatically when a task matches the description.

Common pitfalls

Letting it run migrations. It must stay read-only; keep "never run migrations" in the prompt.
Ignoring rollout order. Most outages come from old code running against new schema for a few minutes.
Not stating the database. Locking behavior differs between Postgres, MySQL and SQLite.

FAQ

Does it support Prisma, Drizzle and Django migrations?

Yes. It reads the generated SQL or migration files. For ORMs that generate SQL at deploy time, ask it to read the generated SQL output.

Why opus for migrations?

Reasoning about locks and rollout order is subtle and mistakes are costly. The reviewer reads few files, so the cost is small.

Can I block dangerous SQL at the tool level?

In Claude Code you can add a PreToolUse hook on Bash that rejects DROP/ALTER. See the db-reader example.

Related subagents

All subagent examples and the Claude Code ↔ Cursor converter