The migration ran at 02:14 UTC on a Tuesday. By 09:00, the support queue held 340 tickets, all variations on the same sentence: "My account shows someone else's orders." The engineer who wrote the script had tested it against a 50,000-row staging copy. Production held 4.2 million rows and a join table nobody had touched since 2019. The new customer_id column had been backfilled by a heuristic — match on email, fall back to phone. Two siblings shared a phone number. Their purchase histories merged into one household, then split apart wrong when the dedupe job ran the second time.
Nobody wrote a bad ALTER TABLE. The SQL was clean. The failure was political: the migration decided who belonged to whom, and it decided without asking.
What a schema actually is
Engineers talk about schema as plumbing — types, constraints, indexes. But a schema is a constitution. It declares what categories exist, which of them are mandatory, and what happens to the entities that don't fit. NOT NULL on a country field is a statement that stateless people cannot be customers. A UNIQUE constraint on username is a ruling that identity is singular and public. A foreign key with ON DELETE CASCADE is a policy that says: when the parent goes, the children go with it, quietly, no hearing.
Every one of those decisions was made by someone, at some point, usually under deadline, usually without a lawyer or an ethicist in the room. The database just enforces it forever.
The migration is where the constitution gets amended
A schema migration is the rare moment when those rulings become visible and contestable. Data that used to fit now doesn't. Columns that were "temporary" have 40 downstream consumers. The backfill script has to guess at intent for every historical row, and its guesses become permanent facts the moment the transaction commits.
This is why migrations fail in ways that look like bugs but aren't. The 2023 incident where a telecom's migration silently reassigned 90,000 subscribers to the wrong billing plans wasn't a coding error — the mapping table was correct for the plans as they existed when it was written. The plans had been renamed twice since. The script faithfully executed an obsolete treaty.
Postgres gives you BEGIN and ROLLBACK. It does not give you a way to un-ring the bell on a customer who opened their app and saw a stranger's address.
Three habits that treat migration as governance
Name the boundary you're redrawing. Before writing the script, write one sentence: "This migration changes the definition of X from A to B, and the rows affected are Y." If you can't fill in Y with a count and a sample, you're not ready. The 02:14 engineer could have run SELECT COUNT(*) FROM customers WHERE phone IN (SELECT phone FROM customers GROUP BY phone HAVING COUNT(*) > 1) in ninety seconds. It would have returned 1,847. That number is the size of the constituency you're about to disenfranchise.
Give the backfill a paper trail. Every heuristic in a migration is a policy choice wearing a comment. Log the rows it couldn't classify, the ones it classified with low confidence, and the ones where two rules disagreed. Treat that log as a legal document, not a debug artifact. When the tickets arrive, it's the only evidence of what you decided on behalf of people who weren't in the room.
Migrate the meaning, not just the bytes. The dangerous migrations aren't the ones that change column types. They're the ones that change what a row means — merging accounts, splitting households, reclassifying a "trial" user as "churned," promoting a "lead" to a "customer." Those deserve a changelog entry written for the affected humans, not just for the next engineer. A user who wakes up as a different kind of entity deserves to know which clause got amended.
The part nobody wants to hear
The cleanest technical answer to most migration disasters is: don't migrate. Add a column, dual-write, backfill slowly, cut over when the old path is provably dead. This is slower, uglier, and requires holding two truths at once for weeks. It is also the only approach that lets you reverse a bad ruling without a data-loss incident.
The 02:14 migration took eleven minutes. The cleanup took six weeks, two customer credits, and one very awkward call with the siblings. The schema is a constitution. Amend it like one — in daylight, with the affected parties named, and with a way back.
Generated by Reportify AI — Automate your team's status reports, standups, and weekly updates. Try free →