How to Plan a Data or System Migration (with a Template)

Cut the scope before the schedule

The first line of a migration plan should say what is not moving and what must keep running during the move. A narrow scope is what makes the schedule believable.

Large datasets are better moved partition by partition than in one pass. Meta describes its ingestion migration in terms of daily data volume, which is the number to plan around.

Plan a dual-write period

You need time where both the old and new stores receive writes, otherwise you cannot verify anything. For data where consistency matters, such as account balances, put the dual-write period and the comparison method at the center of the plan. Mercari’s zero-downtime balance design is a good model for that.

Split large moves into smaller units

When a system carries a large share of global traffic, a single cut-over is hard to undo. GitHub’s move of its Git infrastructure to the cloud to support agent-scale traffic is a case where the scale figure drives how the work is split.

Verify build and runtime changes separately

A move that changes build tooling and test selection has two sets of checks. Stripe’s selective test execution for a 50-million-line Ruby monorepo shows why: the test set itself changes, so compare coverage as well as runtime. Plan one comparison for build output and another for execution.

Template (copy)

## 1. Scope

- What moves, and what stays where it is
- What must keep working during the move

## 2. Phases

| Phase | Work | Done when |
|---|---|---|
| Prepare | | |
| Dual write | | |
| Verify | | |
| Cut over | | |
| Clean up | | |

## 3. Verification

- What is compared, how samples are chosen, what difference is acceptable

## 4. Rollback triggers

- The metric and threshold that trigger a rollback, and the steps

## 5. Owners and schedule

- Who runs each phase, and who signs off