migration-and-contract-review

Migration & Contract Review

Why It Matters Here

A production rollback reverts the merge commit — it does not undo the schema. The old code has to keep running against the new schema until a human decides otherwise, and the system already flags a schema-touching task for a mandatory stage deploy. A migration or contract reviewed only for "does it run" and not "does the PREVIOUS release's code still work against it" is an outage waiting for the next rollback.

Pair with migration-safety (backend-developer, same rules from the authoring side) and spec-authoring's Security & data / Decision record sections for the design-time version of this.

Blocking Checks (Important or Critical)

Editing an applied migration. A migration already run on any environment is immutable; a fix is a new migration.

• ❌ editing 0042_add_status.sql after it merged.
• ✅ 0051_fix_status_default.sql that corrects it.

A stub or empty down/rollback migration. If it can't really be undone, say so and give the operational alternative instead of a down migration that lies.

Drop, rename or retype of a column or table still read by deployed code.

• ❌ ALTER TABLE tasks DROP COLUMN legacy_status; in the same task that stops writing it.
• ✅ stop writing it (task N), deploy, confirm no reads remain (grep_code/consumer check), THEN drop it (task N+1, deploy_depends_on: ["N"]).

ADD COLUMN … NOT NULL with no default, or a volatile default (rewrites the whole table).

• ❌ ALTER TABLE tasks ADD COLUMN priority int NOT NULL;
• ✅ ALTER TABLE tasks ADD COLUMN priority int NOT NULL DEFAULT 0; — a constant default on PG11+ does not rewrite the table.

CREATE INDEX without CONCURRENTLY on a table already carrying rows, or CONCURRENTLY used inside a transaction / a multi-statement file the repo's migration runner wraps in one (check how the runner executes a file before assuming CONCURRENTLY is safe there).

• ❌ CREATE INDEX idx_tasks_status ON tasks(status); on a live table — takes a write lock for the build.
• ✅ CREATE INDEX CONCURRENTLY idx_tasks_status ON tasks(status);, run outside a transaction.