| name | migration-guard |
| description | Reviews a database migration before it ships to make sure it is safe — reversible, non-destructive, and backward-compatible — following the project's database conventions. Use this whenever you create, review, or approve a schema or data migration (e.g. "check this migration", "is this migration safe to deploy?"). |
Review the migration the user points to (or the one in the current diff) for safety.
- Read
docs/conventions/database.md for
the project's migration rules (naming, reversibility, index strategy, allowed
column types) and docs/architecture/database.md
for the current data model it touches.
- Verify reversibility: there is a working
down/rollback path, or the change
is explicitly documented as irreversible with justification.
- Check for data loss: dropping columns/tables, narrowing types, or adding a
NOT NULL column without a default/backfill. Flag any destructive step.
- Check backward compatibility for zero-downtime deploys: can old and new code
run against the new schema during rollout? Prefer expand → migrate → contract
over a single breaking change.
- Check locking / large tables: operations that rewrite or long-lock big
tables (e.g. adding a non-null column, certain index builds). Suggest the safe
variant for the project's database.
- Confirm a rollback plan and that the migration is idempotent / safe to
retry where the tooling allows.
Output: a short verdict (safe / unsafe), the specific risks found, and the minimal
changes to make it safe. If the decision is significant (e.g. an irreversible
migration), recommend recording an ADR in docs/decisions/.
Do NOT run the migration. Do NOT loosen the project's database rules to make a
migration pass — fix the migration instead.
