How to Write a Migration Plan in English

A migration plan that just describes the end state doesn’t help anyone execute the migration safely — the value of a good migration plan is almost entirely in the phasing, rollback strategy, and cutover criteria, which is what actually gets you there without an outage.

Key Vocabulary

Phasing — breaking a migration into discrete, independently verifiable stages rather than one large cutover, so problems surface early in a smaller, lower-risk phase instead of during a single high-stakes event. “Our phasing here has three stages: first, dual-write to both databases while reading from the old one; second, backfill and validate historical data; third, switch reads to the new database. Each phase can be verified independently before moving to the next.”

Rollback strategy — the explicit, tested plan for reverting to the previous state if a phase fails, including how quickly it can be executed, which needs to exist before the migration starts, not be improvised if something goes wrong. “Every phase needs its own rollback strategy written down before we start — for phase one, rolling back just means disabling the dual-write flag, which takes under a minute. That needs to be true and tested, not just assumed.”

Cutover criteria — the specific, measurable conditions that must be true before proceeding to the next phase or completing the migration, defined in advance so the decision isn’t made under time pressure or optimism bias. “We’re not moving to phase three until the cutover criteria are met: data parity between old and new systems above 99.99% for 48 consecutive hours, and zero unexplained discrepancies in the validation report.”

Dry run — a rehearsal of the migration steps against a non-production copy of the system, used to surface unexpected issues, timing problems, or missing steps before attempting the real migration against production. “We’re doing a full dry run against a staging copy of production data before the real migration — it already caught one step in our runbook that assumed a table existed, which it doesn’t in the current schema.”

Common Phrases

• “Is this phasing granular enough that we can verify each step independently?”
• “What’s the rollback strategy for this specific phase, and has it actually been tested?”
• “What are the exact cutover criteria before we move to the next phase?”
• “Have we done a dry run against realistic data before attempting this on production?”
• “What’s our maximum acceptable time to roll back if this phase goes wrong?”

Example Sentences

Describing a phasing approach: “Rather than migrating everything in one weekend cutover, we’re phasing this over three weeks — dual-writing first, validating data parity second, and only switching reads over in the final phase, once we’re confident in the previous two.”

Documenting a rollback strategy: “Rollback strategy for phase two: if data validation shows discrepancies above our threshold, we pause the backfill, leave the dual-write in place, and investigate — reads stay on the old system throughout, so users see no impact even if this phase needs to be paused.”

Stating cutover criteria explicitly: “We won’t cut reads over to the new system until these criteria are met: data parity checks passing for 72 consecutive hours, load testing at 2x expected peak traffic completed successfully, and sign-off from both the data and platform teams.”

Professional Tips

• Break the migration into phasing with independently verifiable stages rather than one large cutover — smaller phases surface problems earlier and limit blast radius when something goes wrong.
• Write a specific, tested rollback strategy for every phase before starting, not just for the migration as a whole — a rollback plan that’s never been tested often turns out not to actually work.
• Define cutover criteria as measurable thresholds in advance — deciding in the moment, under time pressure, tends to produce optimistic go-decisions that skip real verification.
• Always run a dry run against realistic non-production data before attempting the real migration — it reliably surfaces missing steps or bad assumptions cheaply, before they become a production incident.

Practice Exercise

1. Describe a three-phase plan for a hypothetical database migration.
2. Write a rollback strategy for one phase, including how quickly it can be executed.
3. Draft cutover criteria specifying measurable thresholds that must be met before proceeding.