Technical

Find a migration's dependencies before you start

Branch your migration into phases, map which tasks block others, and put a check and a rollback point on every phase.

Start from a template

A migration-plan template you can clone. Fill it in for your own systems and work through it phase by phase.

Clone this template

How it works

Describe where you are migrating from and to, and the model maps what changes. Each phase gets its own branch, and every question under it keeps both systems in context.

  1. Describe the source and target. Say what you run today and what you are moving to. Ask for the components, data flows and integrations that change.

  2. Give each phase a branch. Data migration, traffic cutover, feature parity checks and decommissioning each get one. Under each, ask for tasks, prerequisites and success criteria.

  3. Mark dependencies and risk. Note which tasks block others, such as “migrate user table” before “deploy auth service”. Note which steps you can undo: a DNS switch reverses in minutes, and a schema transform may not reverse at all.

  4. Add a check to every phase. Under each phase, write what to verify before moving on, which metrics show success, and what threshold triggers a rollback. The finished map works as a runbook.

Why a map instead of a task list

A database migration touches the code that queries the database, the pipelines that feed it and the reports that read it. On a map, each of those gets a branch under the database, so you see what else has to change.

Clear dependencies also show what can run in parallel. If “deploy new API” depends on “migrate user schema” but not on “update admin dashboard”, two teams can work at once.

Example

Say you are moving a self-hosted PostgreSQL cluster to AWS Aurora. The map branches into schema compatibility, data transfer, application changes, performance checks and the cutover plan. Under schema compatibility, you list the PostgreSQL features your app relies on, such as LISTEN/NOTIFY and advisory locks, and ask how each behaves on Aurora. A branch on advisory locks shows that your job scheduler, rate limiter and cache invalidation all use them, so each one goes on the test list before cutover.

Now try it yourself

Plan a migration from a monolithic Rails app to microservices
Start by identifying bounded contexts in the monolith — areas with minimal cross-talk make the best first extraction candidates. Plan for a strangler fig pattern where new services handle new traffic while the monolith shrinks incrementally.
How do we handle the shared database during the transition?
Use the database-per-service pattern as the target, but migrate incrementally. Start with a shared database and add service-specific schemas. Then move to change data capture (CDC) with tools like Debezium to replicate data between services until you can cut over fully. Never try a big-bang database split.

Ready to try migration planning?