Database migration rollout

A database migration rollout flowchart showing the expand-and-contract technique: add the new schema, dual-write the old and the new, backfill historical rows, and only then switch reads. If the backfill does not match, writes are reverted; if serving the new schema is wrong, reads go back to the old one. The old schema is removed only after writes to it have stopped.

People draw this type of diagram when a column or table has to change under live traffic, to explain why “just migrate” isn't considered adequate, or to make the two rollback points visible before anyone starts. The two decision points are able to be described more clearly in a flowchart than in words: both failure paths share a rolled-back terminal node, and the contract step is unreachable until the old writes have actually stopped.

Database migration rollout Beginexpand andcontract Add newschema Dual-write oldand new Backfillhistorical rows Backfillmatches? Stop and revertwrites Rolledback Switch reads tonew Servingcorrectly? Revert reads toold Stop writing theold schema Remove oldschema Migrationcomplete Yes No Yes No
Open in editor

Mermaid source

---
title: Database migration rollout
---
flowchart LR
  start([Begin expand and contract]) --> expand[Add new schema]
  expand --> dual[Dual-write old and new]
  dual --> backfill[Backfill historical rows]
  backfill --> verify{Backfill matches?}
  verify -->|No| halt[Stop and revert writes]
  halt --> rolled([Rolled back])
  verify -->|Yes| switch[Switch reads to new]
  switch --> watch{Serving correctly?}
  watch -->|No| revert[Revert reads to old]
  revert --> rolled
  watch -->|Yes| stopOld[Stop writing the old schema]
  stopOld --> contract[Remove old schema]
  contract --> done([Migration complete])

Stock Mermaid vs Line9 on this database migration rollout

Run the same source through the stock Mermaid engine and it often will not look as good. In some cases, Mermaid is able to deliver a usable graph, but not always. On this one:

The same database migration rollout through stock Mermaid — a band seven times wider than it is tall, with both rollback paths stacked on long No arcs at the far right
Stock Mermaid · same source View full size ↗

The stock Mermaid renderer stretches the expand-and-contract sequence into a band seven times as wide as it is tall, so that any display or printout inevitably wastes a lot of screen or paper space. Line9 folds the same source into a 1.6:1 aspect ratio, making it far more suitable for easy consumption and legibility.

For a fuller product comparison — layout, export, CLI, and pricing — see Line9 vs mermaid.live.

Render your own

Paste any Mermaid flowchart into the free online editor — no account needed. Prefer the terminal? Install the line9 CLI (free for personal use).

More scenarios on the Mermaid examples hub.