Database Migration,
as a sequence diagram.

A database migration sequence diagram maps out the precise order of interactions between your application, migration tooling, and database engine during a schema change—without taking the system offline. It visualizes each step: deploying backward-compatible schema changes, running dual-write phases, backfilling data, switching read paths, and finally cleaning up legacy columns or tables. By laying out these interactions in a time-ordered flow, the diagram makes implicit coordination explicit, helping every stakeholder understand what happens, in what order, and which component is responsible at each stage.

## When to Use This Template

This template is most valuable when your team is planning a non-trivial schema change on a production database that must remain available—such as adding a non-nullable column, renaming a table, splitting a column, or changing a data type. It is equally useful during incident post-mortems to reconstruct what went wrong during a previous migration, or as onboarding material to teach junior engineers the expand-contract (parallel-change) pattern. DevOps engineers can use it to align deployment pipelines with database change windows, while DBAs can annotate it with locking behavior and transaction boundaries to surface hidden risks before a single line of SQL is executed.

## Common Mistakes to Avoid

One of the most frequent errors teams make is skipping the backward-compatibility validation step—deploying a new schema before the old application version can still read from it. In a sequence diagram this gap is immediately visible as a missing interaction arrow. Another pitfall is collapsing the backfill and cutover phases into a single step, which hides the risk of long-running transactions causing table locks. Teams also often omit the rollback path entirely; a well-drawn sequence diagram should show the failure branch alongside the happy path so on-call engineers know exactly which compensating actions to take. Finally, avoid treating the migration as a purely database-side concern—your sequence diagram should always include the application deployment actor, because zero-downtime migrations are a choreography between code releases and schema changes, not a solo database operation.