FREE TEMPLATE

Technical Migration Plan Template

Every rollback closes on a nameable event. This plan puts that window in hours beside each check's detection time, then reports which checks still fit.

Edit with AI Download (.docx + .csv)

Free download · No account needed

What you get

Pack of 9 files: 6 documents, 3 spreadsheets

Technical Migration Plan Template

How Rollback Windows WorkDocument
Migration StandardDocument
Migration PlanDocument
Cutover RunbookDocument
Rollback ProcedureDocument
Comms PlanDocument
Sequencing and Rollback RegisterSpreadsheet
Validation ChecksSpreadsheet
Risk RegisterSpreadsheet

Every migration plan has a rollback section. Almost none of them says when the rollback stops working, and it always stops working. The moment the new cluster takes its first write, the moment the old version's artifact is garbage collected, the moment a retention boundary passes. So on day three, when the problem surfaces, nobody has worked out whether going back is still possible. It usually is not, and the moment it stopped being possible had a name.

The reference tooling is blunt about this. Postgres' upgrade documentation ships a six-branch revert tree keyed on which mode ran and whether the new cluster was started, and two branches end in restoring from backup. Kubernetes says that once an old ReplicaSet is deleted you lose the ability to roll back to that revision, keeping ten by default. A stock blue-green rollout scales the previous version down after thirty seconds. None of that is unusual, and none of it appears in a migration plan.

So a rollback is a window, and every window is a number. This pack derives it from the ending event, then joins it to each validation check's detection time. Harlow Grid's worked plan has nine phases and fourteen checks. Seven checks can trigger their own rollback. The daily billing reconciliation needs a billing cycle, so it answers twenty-six hours after a cutover whose rollback lapses in eight. It was filed under cutover validation, where it had sat unexamined for a month.

The check that answers after the rollback has gone

Every window is derived from its ending event, and every coverage column is a join. Neither is typed in.

Technical Migration Plan Template

SequencingValidation ChecksRisk Register

Sequencing

Sequencing and Rollback Register

Harlow Grid, a fictional energy retailer moving its metering platform onto managed Postgres 16 and Kubernetes. Rollback Ends When is an event; the hours follow from it.

Phase	What moves	Rollback	Ends when	Window	Rehearsed	One-way
P1	Target cluster stood up, no traffic	Delete the cluster	Nothing, while no data has been written	unbounded	Not needed	No
P2	Expand-only schema change on the target	Drop the added columns and indexes	The application starts writing them, at P6	unbounded	2026-09-16	No
P3	Logical replication, old primary to target	Drop the subscription	Nothing, while writes go to the old primary	unbounded	2026-09-18	No
P4	New app deployed, preview service only	Scale the deployment to zero	Nothing, while no production traffic reaches it	unbounded	2026-09-22	No
P5	5 percent of read traffic to the target	Revert the traffic weight	Old ReplicaSet scaled down after the promotion delay	0.5h	2026-09-24	No
P6	All reads, and the new columns start being written	Revert the weight, stop writing the columns	Old ReplicaSet scaled down after the promotion delay	0.5h	Never	No
P7	Writes cut over to the target	Reverse replication, target to old primary	The reverse slot falls outside WAL retention	8h	Never	Yes
P8	Old application fleet decommissioned	Redeploy the retained previous revision	ReplicaSet garbage collected past a limit of 3	unbounded	Never	No
P9	Old Postgres 13 cluster dropped	Restore from backup, measured at 6h	Backup retention expires at 14 days	336h	Never	Yes

Phase

What moves

Rollback

Ends when

Window

Rehearsed

One-way

Target cluster stood up, no traffic

Delete the cluster

Nothing, while no data has been written

unbounded

Not needed

Expand-only schema change on the target

Drop the added columns and indexes

The application starts writing them, at P6

unbounded

2026-09-16

Logical replication, old primary to target

Drop the subscription

Nothing, while writes go to the old primary

unbounded

2026-09-18

New app deployed, preview service only

Scale the deployment to zero

Nothing, while no production traffic reaches it

unbounded

2026-09-22

5 percent of read traffic to the target

Revert the traffic weight

Old ReplicaSet scaled down after the promotion delay

0.5h

2026-09-24

All reads, and the new columns start being written

Revert the weight, stop writing the columns

Old ReplicaSet scaled down after the promotion delay

0.5h

Never

Writes cut over to the target

Reverse replication, target to old primary

The reverse slot falls outside WAL retention

Never

Yes

Old application fleet decommissioned

Redeploy the retained previous revision

ReplicaSet garbage collected past a limit of 3

unbounded

Never

Old Postgres 13 cluster dropped

Restore from backup, measured at 6h

Backup retention expires at 14 days

336h

Never

Yes

Nine phases, ordered by rollback rather than by convenience: four unbounded first, then the two half-hour phases, then the one-way cutover. Four rollbacks have never been rehearsed and they are the last four, which is the ordinary pattern and runs exactly opposite to where the stakes are. P2 is the coupling nobody spots: its rollback expires because of P6, two weeks later, so the register names the ending event as a phase identifier rather than a date. P8's window is measured in deploys, not hours, because the revision history limit is 3.

Validation Checks

A baseline measured on the old system before anything moved, beside the threshold. Detection is hours until the verdict means anything, not how long the query runs.

Check	Phase	Asserts	Baseline	Threshold	Detection	Window	Can gate it
V-01	P3	Every row present in the target, ten largest tables	1,412,880,310 rows on the old primary	Exact match per table	0.5h	unbounded	Yes
V-03	P5	Read latency p99 does not regress	p99 214ms, 14 days	Under 250ms	0.25h	0.5h	Yes
V-05	P6	Meter reads identical for a sampled 5,000 meters	5,000 of 5,000 on the old primary	5,000 of 5,000	2h	0.5h	No, 1.5h late
V-06	P6	The new columns are written on every insert path	17 insert paths, enumerated	17 of 17	1h	0.5h	No, 0.5h late
V-07	P7	No write is lost during the cutover	Sequence high-water marks, both clusters	Zero gap	0.25h	8h	Yes
V-08	P7	Daily billing totals agree between the systems	4,180,442 kWh per day, 90 days	Within 0.01 percent	26h	8h	No, 18h late
V-09	P7	Monthly invoice values agree, 2,000 accounts	Invoices already issued, September	Within one penny	744h	8h	No, 736h late
V-11	P8	No client still resolves the old endpoint	9 distinct client identities, 7 days of logs	Zero for 72 hours	72h	unbounded	Yes
V-12	P6	The system is stable	No baseline was measured	None declared	—	0.5h	No, nothing to compare
V-13	P7	Performance is acceptable under load	No baseline was measured	None declared	—	8h	No, nothing to compare
V-14	P9	Nothing depends on the old cluster	No baseline was measured	None declared	—	336h	No, nothing to compare

Check

Phase

Asserts

Baseline

Threshold

Detection

Window

Can gate it

V-01

Every row present in the target, ten largest tables

1,412,880,310 rows on the old primary

Exact match per table

0.5h

unbounded

Yes

V-03

Read latency p99 does not regress

p99 214ms, 14 days

Under 250ms

0.25h

0.5h

Yes

V-05

Meter reads identical for a sampled 5,000 meters

5,000 of 5,000 on the old primary

5,000 of 5,000

0.5h

No, 1.5h late

V-06

The new columns are written on every insert path

17 insert paths, enumerated

17 of 17

0.5h

No, 0.5h late

V-07

No write is lost during the cutover

Sequence high-water marks, both clusters

Zero gap

0.25h

Yes

V-08

Daily billing totals agree between the systems

4,180,442 kWh per day, 90 days

Within 0.01 percent

26h

No, 18h late

V-09

Monthly invoice values agree, 2,000 accounts

Invoices already issued, September

Within one penny

744h

No, 736h late

V-11

No client still resolves the old endpoint

9 distinct client identities, 7 days of logs

Zero for 72 hours

72h

unbounded

Yes

V-12

The system is stable

No baseline was measured

None declared

—

0.5h

No, nothing to compare

V-13

Performance is acceptable under load

No baseline was measured

None declared

—

No, nothing to compare

V-14

Nothing depends on the old cluster

No baseline was measured

None declared

—

336h

No, nothing to compare

Fourteen checks in the shipped sheet. Seven can trigger the rollback they exist to trigger. Four have a real baseline and answer after the window has closed. Three cannot fail at all. V-05 and V-06 both failed in rehearsal, at 4,997 of 5,000 and 15 of 17, which is how a rounding change and two batch jobs nobody had grepped for were found. Neither would have failed in time if it had first run at cutover. V-08 is the one that changed the plan: raising the old primary's write-ahead log retention from 8 hours to 48 brings it inside the window with 22 hours to spare, and costs 340GB on a machine being decommissioned anyway.

Risk Register

Every risk names one check and one rollback, both by identifier. Detectable in time is a join, not a judgement.

Risk	Phase	Severity	Description	Detected by	Detection	Window	In time
R-05	P7	Critical	Writes lost between stopping the old path and starting the new	V-07	0.25h	8h	Yes
R-06	P7	Critical	Billing totals diverge because a rounding rule differs	V-08	26h	8h	No, 18h too late
R-07	P7	Critical	Invoice values change for accounts with a mid-month tariff switch	V-09	744h	8h	No, 736h too late
R-10	P9	Critical	Something still depends on the old cluster after it is dropped	V-14	—	336h	No, the check has no baseline
R-03	P6	High	Sampled reads disagree after a data type widened	V-05	2h	0.5h	No, 1.5h too late
R-04	P6	High	An insert path nobody enumerated skips the new columns	V-06	1h	0.5h	No, 0.5h too late
R-09	P8	High	A client nobody knows about still calls the old endpoint	V-11	72h	unbounded	Yes
R-12	P7	High	Throughput collapses under a load pattern the test missed	V-13	—	8h	No, the check has no baseline
R-01	P3	High	Replication falls behind and the target diverges	V-02	1h	unbounded	Yes
R-11	P6	Medium	The system misbehaves in a way nobody predicted	V-12	—	0.5h	No, the check has no baseline

Risk

Phase

Severity

Description

Detected by

Detection

Window

In time

R-05

Critical

Writes lost between stopping the old path and starting the new

V-07

0.25h

Yes

R-06

Critical

Billing totals diverge because a rounding rule differs

V-08

26h

No, 18h too late

R-07

Critical

Invoice values change for accounts with a mid-month tariff switch

V-09

744h

No, 736h too late

R-10

Critical

Something still depends on the old cluster after it is dropped

V-14

—

336h

No, the check has no baseline

R-03

High

Sampled reads disagree after a data type widened

V-05

0.5h

No, 1.5h too late

R-04

High

An insert path nobody enumerated skips the new columns

V-06

0.5h

No, 0.5h too late

R-09

High

A client nobody knows about still calls the old endpoint

V-11

72h

unbounded

Yes

R-12

High

Throughput collapses under a load pattern the test missed

V-13

—

No, the check has no baseline

R-01

High

Replication falls behind and the target diverges

V-02

unbounded

Yes

R-11

Medium

The system misbehaves in a way nobody predicted

V-12

—

0.5h

No, the check has no baseline

Twelve risks in the shipped sheet: five detectable while the rollback still exists, four detected only after it expired, three with no detection at all. Four risks are critical and three of them are not in the first group. Three of the four sit on P7, the eight-hour one-way phase. R-10 is the quietest: its check has no baseline, so a critical risk on the phase with the longest window in the plan currently has no detection except a repeated notice to everyone holding a credential on the old cluster, which is detection by outage.

Install the migration plan pack

What comes in the pack

Sequencing register with the ending event beside the window

One row per phase. Rollback Ends When names the event: the reverse slot falling outside write-ahead log retention, the old ReplicaSet being garbage collected past the revision limit, the promotion delay expiring, the backup ageing out. The hours follow from the event rather than the other way round, because the event can be changed and a guessed number cannot. Unbounded is a real value and four of the nine worked phases carry it, which is what lets attention go to the five that do not.

A rehearsed column, because an unrehearsed rollback is a paragraph

Rehearsing tells you two things nothing else will: whether the rollback works and how long it takes. The second is the number the window has to accommodate, and a six-hour rollback inside an eight-hour window is two hours of decision time rather than eight. Four of the nine worked rollbacks have a rehearsal date, one is recorded as not needed, and four have never been run. They are the last four, which is the ordinary pattern and runs exactly opposite to where the stakes are.

Validation Checks that are comparisons, not a checklist

Every row carries a baseline measured on the old system on real traffic before anything moved, with its source and date, beside the threshold and the reading. Eleven of fourteen worked checks have one. The three that do not read "the system is stable," "performance is acceptable under load" and "nothing depends on the old cluster," and none of them can fail. That outcome has a name in the reference tooling rather than being a rhetorical point.

The join, which is the whole reason detection time is a field

Detection time is hours from the phase landing to the check producing a verdict that means anything, not how long the query runs. Set it beside the phase's window and one column falls out: can this check trigger the rollback it exists to trigger. Seven of fourteen can. The monthly invoice comparison answers 736 hours after its rollback ended, which is thirty days and sixteen hours, and it is still a good check. It was never a gate.

Risk Register that inherits the join

Every risk names one check and one rollback by identifier, and the sheet reports whether detection lands while the rollback still exists. Five of twelve worked risks do. Four are detected only after it expired. Three have no detection at all, because their check has no baseline. Four risks are critical and three of those four are in the second or third group, which is a sentence nobody would sign off if it were on the front page, so it is on the front page.

A runbook, a per-phase rollback procedure and a comms plan keyed on the phase

The cutover runbook names one person who calls the rollback and decides the no-go readings in advance, because at 02:40 with a graph moving the wrong way nobody invents a threshold well. The rollback procedure has nine sections rather than one, since there is no such thing as the rollback for a migration. Every notice states the window in hours, which is the line that gets replies from integration partners. The decision to migrate at all belongs upstream, in an architecture decision record.

How it works

1
Send the architecture and the config
Current and target state, the dependency map, traffic data, a runbook draft. River also goes looking for the two things that set every window and nobody sends: retention settings, and the revision-history and scale-down configuration.
2
Phases are cut by their rollback
A phase is a change that can be undone as a unit, so the test is whether reverting half of it leaves a state nobody thought about. Then they are ordered with the unbounded rollbacks first and the one-way phases as late as the dependencies allow.
3
Every window is derived from its ending event
River reads the effective configuration rather than the documented default, names the event, and computes the hours. It also names the single change that would most extend the tightest window, which is usually one setting on a system being decommissioned anyway.
4
Then the join tells you what you have
Each check gets a baseline, a threshold and a detection time, and the coverage columns compute. You get the count of real gates, the risks nobody could catch in time, and the checks that cannot fail. Reconstruct an undocumented system first if you need to, with legacy codebase documentation.

Frequently asked questions

Why does a rollback need an expiry date?

Because it has one whether you write it down or not. Postgres' revert instructions branch on whether the new cluster was ever started, and if it was in link mode the old cluster is unsafe and has to come back from backup. Naming the event is what turns that from a surprise into a number.

How do you get the window in hours?

From the ending event, by reading the effective configuration rather than a default. Write-ahead log retention gives a reverse-replication window. Backup retention gives a restore window. A promotion delay gives a traffic-shift window, and the stock default is thirty seconds, which is worth knowing before you rely on it.

What if a rollback genuinely never expires?

Record it as unbounded, which is a real value, and never put a false clock on it. Four of the nine worked phases are unbounded: a cluster nobody has written to, an expand-only schema change with nothing reading the new columns, a deployment behind a preview service. Knowing which four is what lets you spend attention on the rest.

Why can't a check without a baseline fail?

Because there is nothing for the reading to contradict. "Performance is acceptable" admits no measurement that disproves it. Argo Rollouts evaluates against a success condition and a failure limit declared before the rollout, and names the outcome when neither resolves: Inconclusive. Three worked checks sit there before the migration has started.

What do I do about a check that answers too late?

Three honest responses. Extend the window, which is usually one retention setting on a system being decommissioned anyway. Shorten the detection by running the check as a shadow against both systems before cutover. Or accept in writing on the row that the recovery is a forward fix. What is not honest is leaving it under cutover validation.

Is a rollback window the same as an outage budget?

No, and conflating them is why the number goes missing. A window is how long the option to go back exists. How long you will tolerate being broken before using it is a separate and usually much shorter number. The rollback's own duration is a third. All three go on the row and they answer different questions.

Does this replace the design document for the migration?

No. Proposing the change belongs in an RFC register, and the target architecture belongs in a solution architecture document. This pack starts once the destination is agreed and the only remaining question is whether you can get back.

Sources

Written by

Chandler Supple

Co-founder & CEO, River

Chandler has spent the last six years working in AI, building tools for millions of users and Fortune 100 companies. In 2025, he co-founded River to build a new kind of operating system for AI agents.

LinkedIn GitHub X

Reviewed by

Brian Joseff, Co-founder, River

LinkedIn X

Related engineering templates

RFC and design doc pack

Propose the change and finish deciding it, with a decision date and the objections nobody answered.

Architecture decision record pack

Hold the decision after it is taken, and keep the answer to which records are still in force true.

Threat model pack

Threat model the target design before it ships, against a denominator computed from the census.

Solution architecture document

Assemble the current and target architecture from the diagrams, specs and infrastructure config that already exist.

More free templates

Architecture Decision Record Template

Free architecture decision record template in Word and CSV, plus the conventions a team settles once and a register reconciling each status against its file.

Engineer Onboarding Documentation Template

Free engineering onboarding documentation template with a monthly sweep that reverifies your setup guide and a question log that feeds gaps back into it.

Engineering RFC and Design Doc Template

An engineering RFC template where a status is three facts: the state, the date it ends, and the objections nobody answered. Free installable pack.

STRIDE Threat Model Template

A STRIDE threat model template that counts how many cells your design makes applicable, then reports how many anyone answered. Free installable pack.

Find out which rollback you no longer have

Send the architecture and the config. River derives every window from its ending event, then reports which checks still fit.

Install the migration plan pack

Technical Migration Plan Template

The check that answers after the rollback has gone

Sequencing and Rollback Register

Validation Checks

Risk Register

What comes in the pack

Sequencing register with the ending event beside the window

A rehearsed column, because an unrehearsed rollback is a paragraph

Validation Checks that are comparisons, not a checklist

The join, which is the whole reason detection time is a field

Risk Register that inherits the join

A runbook, a per-phase rollback procedure and a comms plan keyed on the phase

How it works

Send the architecture and the config

Phases are cut by their rollback

Every window is derived from its ending event

Then the join tells you what you have

Frequently asked questions

Why does a rollback need an expiry date?

How do you get the window in hours?

What if a rollback genuinely never expires?

Why can't a check without a baseline fail?

What do I do about a check that answers too late?

Is a rollback window the same as an outage budget?

Does this replace the design document for the migration?

Sources

Chandler Supple

Related engineering templates

More free templates

Find out which rollback you no longer have