Skip to content

commandDatabases

Schema Diff Review

Reviews a schema change or migration diff for risk, missing indexes and rollback, and returns a verdict with line references.

npx workspacetemplates add schema-diff-review --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/schema-diff-review.md15 lines · 1.2 KBFile
---
description: Reviews a schema change or migration diff for risk, missing indexes and rollback, and returns a verdict with line references.
argument-hint: "[branch or commit range, default current diff]"
---

Review the schema change: $ARGUMENTS (branch, commit range, or empty for the current diff against main).

1. Run `git diff <base>...HEAD --stat` and read every changed migration, model and schema file, and the tables they touch.
2. Check each statement for: locks on large tables, rewrites of the table, dropped or truncated columns, narrowing type changes, NOT NULL or unique constraints added to existing data, renamed columns that old code still reads.
3. Check design: missing foreign keys, missing indexes on new foreign keys and filtered columns, duplicate or unused indexes, wrong types for money and time, missing defaults.
4. Check order: can the old application version run against the new schema, and the new code against the old schema?
5. Check rollback: is there a working down step, and what data is lost if used?
6. Do not edit or run anything.

Return a verdict (approve, change, block), then findings in a table: severity, file:line, problem, fix. End with the rollback plan in 3 steps and ask if you should draft the fixes.

What it does

Schema changes are the riskiest part of a pull request because they cannot be undone as easily as code. This command reads the diff and the schema around it, then judges it the way a careful database engineer would.

You get a verdict of approve, change or block, each finding tied to a file and line, and a plan for how to roll back if the deploy goes wrong.

Example

you › /schema-diff-review feature/invoices

agent › Verdict: change.
High: migrations/0061.sql:14 creates index on payments(invoice_id) without CONCURRENTLY, locks writes.
Medium: invoices.total is FLOAT, use numeric(12,2).
Low: no index on invoices.customer_id.
Rollback: down step drops the table, so export first. Draft fixes?

Questions

Does it run the migration to check it?
No. It judges the diff by reading, and suggests testing on a copy of the data.
What do the verdicts mean?
Approve means no blockers, change means fix the listed items first, and block means the change can cause data loss or an outage.
  • Add Index

    CommandDatabases

    Free
  • Explain Query

    CommandDatabases

    Free
  • Seed Database

    CommandDatabases

    Free
  • Write Migration

    CommandDatabases

    Free