The Runbook for a Version Migration Nobody Notices

The core technique behind a zero downtime migration is running both versions side by side long enough to prove the new one behaves correctly under real traffic, before the old version goes away. For a database, that means dual writes to old and new schemas with reads still coming from the old one. For a service upgrade, that means a canary population on the new version while the majority stays on the old one. The point isn't speed, it's having a safe, cheap way to compare behavior before you're committed.

Skipping this step to save a week is how a subtle behavior change in the new version reaches every user at once instead of the small canary group you were watching closely.

Break the migration into steps small enough that any single one can be rolled back without touching the others. Add the new schema or new code path without removing the old one. Start writing to both, still reading from the old one. Switch reads to the new path once writes have been verified for a full traffic cycle, typically at least one business week so you catch anything that only happens on a specific weekday or during a batch job. Only remove the old path once the new one has run alone, in production, long enough that rolling back would mean redoing work rather than flipping a flag.

If a step can't be undone in minutes, it's not a step, it's the whole migration disguised as one.

A reversible migration usually moves in this order:

1. Add the new schema or code path alongside the old one, without removing anything from the old path.
2. Start writing to both paths while reads still come from the old one, so nothing depends on the new path yet.
3. Verify the new writes across a full traffic cycle before you trust them for reads.
4. Switch reads to the new path once those writes are confirmed correct, keeping the old path available for rollback.
5. Remove the old path only after giving it a real expiration date and an owner.

Write down, before the migration begins, exactly what error rate, latency threshold, or specific failure would trigger a rollback, and who has the authority to call it. Deciding this during an active incident means someone is doing math under pressure instead of checking a number against a threshold that was already agreed. The trigger should be conservative early in the rollout, when you're watching a small percentage of traffic, and can loosen slightly once more of the fleet has proven stable on the new version.

This single document, agreed before the first line of the migration runs, is usually the difference between a rollback that takes five minutes and one that takes an hour of debate first.

A deploy dashboard turning green tells you the new version started. It doesn't tell you it's correct. Watch application level signals, error rate on the specific endpoints touched by the migration, latency at the percentile that matters for your product, and any business metric downstream of the migrated component, like checkout completion if you migrated the payments service. Deployment frequency and lead time matter for how fast you can iterate, but they don't tell you whether this specific migration behaved: the highest performing engineering organizations manage on-demand deployment, essentially daily releases¹, and that speed is only worth having if what ships is actually correct.

Set the dashboard up before you start, not after something looks wrong.

The most common failure after a successful migration isn't technical, it's that the old code path never actually gets removed. It sits there, unmaintained, until the next security patch or dependency bump forces someone to touch it again, at which point nobody remembers why it's still there. Set a calendar date for removing the old path when you start the migration, not a vague someday, and treat that removal as part of the migration's definition of done rather than a separate future project.

A migration that's mostly done and stuck there for a year is worse than one that hasn't started, because it looks finished on every dashboard that matters except the one that shows dead code.

Even an invisible migration touches other teams: support needs to know a behavior might shift slightly during the parallel run, and whoever owns the on call rotation needs to know a rollback trigger exists and what it looks like when it fires. Write a short, plain description of what's changing, when, and how to tell if something's wrong, and share it before the migration starts rather than after someone notices a symptom and has to guess whether it's related. This costs fifteen minutes and saves the alternative: a support ticket escalated as a mystery incident that turns out to be the migration working exactly as planned.

The goal isn't a big announcement, it's making sure nobody outside engineering is caught off guard by something that was, by design, supposed to be unremarkable.