Write a migration plan
Phases a schema or API change into expand, migrate and contract, each one deployable on its own and reversible without touching later data.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your prompt
Model-agnostic — works in Claude, ChatGPT, Gemini or any AI chat.
Why this prompt works
- →Enforcing expand-migrate-contract as the structure rules out the default unsafe plan: a single deploy that renames or drops something while old code paths are still reading it.
- →Requiring each phase to survive being "left running for days" targets real deploys, where phases don't happen back-to-back and one that only works if the next lands immediately will break.
- →A rollback stated per phase, scoped to leave later phases' data untouched, is what makes the plan actually reversible rather than reversible in theory — it matters exactly when something goes wrong mid-migration.
Part by part
- expand-migrate-contract pattern
- A named pattern rather than an ad-hoc plan, so each phase has a defined purpose. It is the standard approach precisely because each phase is separately reversible.
- Expand (add the new shape alongside the old, additive only)
- Additive changes are safe to deploy at any time and safe to leave in place indefinitely, which is what makes the first phase low-risk.
- with the old shape still present as a fallback
- The property that makes the middle phase revertible. Once the old shape is gone, rollback stops being a deployment and starts being a data-recovery exercise.
- safe to leave running for days if the next phase is delayed
- Migrations stall — a backfill takes longer than expected, a client will not upgrade. A plan that assumes phases follow immediately breaks the first time reality intervenes.
- state the rollback: what it takes to revert just that phase
- Per-phase rollback rather than a single plan-wide one. Reverting phase two after phase three has written data is the situation that actually causes outages.
Common mistakes
Write a migration plan for renaming this column.Without the pattern named, the plan is usually a single step: rename the column and deploy. That requires every reader and writer to change simultaneously, which is a synchronised deployment and therefore an outage.
How do I migrate this safely?Safely is undefined, so the answer covers backups and testing rather than the structure of the change. The safety here comes from each phase being independently deployable, which has to be asked for.
Write a migration plan with a rollback plan.A single rollback at the end implies the whole migration reverts as one unit. It does not — once later phases have written data, reverting an earlier one is a different and much harder problem.
Questions
Why three phases rather than one?
Because a single-phase change requires every writer and reader to switch at the same instant. Splitting it means each deployment is compatible with both the old and new state, so nothing has to be coordinated.
How long should the middle phase last?
As long as it takes for every client to move, which is often longer than planned — particularly with mobile apps or third-party consumers. The plan should tolerate weeks rather than assume days.
What most often goes wrong?
Contracting too early. Removing the old shape while something still reads it is the failure that causes an outage, and it is usually caused by an incomplete inventory of consumers rather than by a bad plan.
Does this apply to API changes as well as schemas?
Yes, and the constraint is tighter, because you control deployment of a database and not of your clients. An API contract phase may have to wait months, or never happen at all for a public endpoint.