Technical Migration Plan Template

Start by describing the system as it runs today and the one you are moving to. If the target is not written down yet, write a solution architecture document first. Then list everything that touches the old system: services, batch jobs, reports, partner integrations and people with direct database access.

Build that list from evidence. Access logs show who actually connects and the grant list shows who could, but logs only help if they cover your longest cycle. Three days of logs can miss a weekly job.

Then collect the facts the plan depends on:

• Baselines from real traffic on the old system: row counts, latency, error rates and business totals
• Retention for anything a rollback would need, such as database logs and backups
• How many old versions your deployment tool keeps, and how soon it shuts the old one down
• Any hard deadline, such as a data center lease ending

A phase is a change you can undo as a unit. The test is the rollback: if undoing half of a step would leave the system in a state nobody planned for, the step is one phase.

Where data or an interface changes shape, use what Danilo Sato, writing on Martin Fowler's site, calls parallel change, or expand and contract¹. Add the new version beside the old, move every client across, then remove the old one. Sato warns that skipping the last step can leave you worse off than when you started.

Order the phases by their rollback. Put phases whose rollback never expires first and those on a clock next. Leave one-way phases, the ones you cannot reverse once their window closes, as late as the dependencies allow.

Move traffic in small steps. Google's Site Reliability Workbook shows the arithmetic: a release that fails 20% of requests, tried on 5% of traffic, fails 1% overall².

For each phase, write the rollback as a specific act, such as "shift the traffic weight back." Then name the event that ends it. Four kinds cover most migrations.

PostgreSQL's upgrade guide says that after a link-mode upgrade, once the new cluster has started, the old cluster is unsafe to use and must be restored from backup³. Kubernetes keeps 10 old versions of a deployment by default and warns that once one is deleted, you lose the ability to roll back to that revision⁴.

Argo Rollouts, which runs blue-green releases on Kubernetes, scales the old version down 30 seconds after the switch⁵ unless you change the delay. Read each setting from the running system, since a default may have been changed. Then turn each event into a window: hours from when the phase lands, deploys if version cleanup ends it, or "unbounded" if nothing does.

A validation check is a comparison, not a hope. "Performance is acceptable" cannot fail, because nothing was measured to compare it against. Each check needs four parts: what it asserts, a baseline, a threshold and a detection time.

Measure baselines on the old system's real traffic, not a load test, and record their source and date. Detection time is how long until the answer means anything, not how long the query runs. A row count answers in minutes, but a daily billing reconciliation needs a full day.

Set each check's detection time beside its phase's rollback window. The Site Reliability Workbook gives similar advice for canary releases: measure over intervals no longer than the canary itself². A check that answers after its rollback expires cannot trigger it, so pick one fix and write it on the row:

• Extend the window, for example by keeping logs or backups longer
• Shorten detection by running the check on both systems before cutover, using past data
• Accept in writing that the risk will be fixed forward, and name an owner

Practice each rollback before its phase, one-way phases first, to learn whether it works and how long it takes. A rehearsal on an empty copy proves only that the commands run, so use production-sized data. AWS, in the Well-Architected guidance it gives customers, says a rollback or fix-forward plan should be documented and tested before the change reaches production⁶.

Keep the fallback ready for longer than the first night. Google Cloud's guide for customers moving databases to its platform warns that a fallback might be needed days or weeks after the switchover⁷. It treats the fallback as a full migration in reverse, testing included.

Every one-way phase needs a runbook with times, not intentions. Name the roles before the night and give one person, the cutover lead, the call on rolling back. Write preconditions as facts someone verifies by query at a stated time, and decide the no-go readings in advance.

Send a notice for each phase that people outside the team will see, not one announcement for the whole move. Say what changes for the reader, when, what a problem would look like, who to contact and how long you can undo it. A reply saying "our nightly job reads that table" is a dependency you can still plan for.

Before cutover, business teams can test their own workflows with a UAT test plan. Afterward, a post-implementation review compares what the move promised with what it delivered. The template on this page has the three registers, a cutover runbook and a comms plan, with a worked example. River can build the registers from your own plan.