safe-migrations

Safe migrations — the schema change and the safe path to it are different artifacts

The single most expensive junior mistake in backend work: writing the migration for the final state instead of the safe path to it. ALTER TABLE users RENAME COLUMN email TO email_address looks correct — and it is correct, for a world where the deploy is instantaneous. Real deploys are rolling: for minutes (or hours, or days if the deploy fails), old code and new schema run against each other. The rename ships, old pods still SELECT email, and production is down before the deploy finishes. Every rule below exists because the database outlives and overlaps every version of the code that touches it.

How to apply this

Before writing any migration, answer one question: "will the previous release's code still work against the schema this migration produces?" If no, the migration must be split into stages. Then walk the change through the expand → migrate → contract sequence, and run the self-check before shipping.

---

1. The core law: every migration is compatible one release in each direction

During a rolling deploy, blue/green switch, or a failed-deploy rollback, the schema meets both the old and the new code. So:

• The schema after the migration must work with the previous release's code (deploy in progress, or rolled back).
• The current code must work with the pre-migration schema only if your platform runs code before migrations — know your ordering; most run migrations first.

This is the invariant everything else derives from. A migration that requires the new code to already be everywhere is a migration that requires downtime — and nobody scheduled any.

2. Expand → migrate → contract

Any breaking change (rename, drop, type change, moving data) decomposes into three phases across separate releases:

1. Expand — add the new thing alongside the old: a new nullable column, a new table, a new index. Purely additive; old code doesn't notice.
2. Migrate — teach the code to write to both old and new (dual-write), backfill existing rows (section 4), then switch reads to the new location. Each of these can be its own deploy; each is individually reversible.
3. Contract — only after a full release cycle where nothing reads or writes the old location: drop it. The drop ships alone, in a release that changes nothing else about that data.