Agent-Written Down Migrations or Human Recovery Runbooks: A Rehearsal-First Debate

Description and use

Teams can reliably rollback additive migrations while ensuring destructive changes have documented recovery paths, reducing incident risk and improving PR quality.

Problem

Teams often author only up migrations, leaving down migrations or recovery runbooks missing, causing rollback failures when destructive changes occur.

Outcome

Teams can reliably rollback additive migrations while ensuring destructive changes have documented recovery paths, reducing incident risk and improving PR quality.

Workflow

• 1. Classify migration change class (additive, backfill, index, drop, constraint).
• 2. Apply decision rule: if DDL can restore state, allow agent to author down migration; otherwise, require human runbook.
• 3. Add rule to pull request checklist.
• 4. Run CI rehearsal script (rehearsal.sh) against disposable DB to verify up/down schema equivalence and that up changes something.
• 5. If rehearsal passes, merge; if not, fail PR and address issues.
• 6. For destructive changes, create and document a human-authored recovery runbook.
• 7. Store runbook in repository and reference in PR.
• 8. Periodically review runbooks for long-lived branches.

Evidence

Author the down migration with an agent only when DDL alone can restore the previous state; anything that destroys values needs a human-authored recovery runbook.

Source

The script below rehearses an up/down pair and fails when the down-path is not schema-equivalent, or when the up-path changed nothing.

Source