Zero-downtime schema migration template

Expand and contract: change a live database schema in small, reversible deploys, with the table before, during and after.

Use this templateFree, opens in your browser. No sign-up.

Zero-downtime schema migration template
Rules
1. Expand: add first_name, last_name (nullable)
2. Deploy: write both old and new columns
3. Backfill in batches of 10k rows
Counts + checksums match?
Fix the backfill, re-run
4. Switch reads to new columns (flag)
5. Stop writing full_name
6. Contract: drop full_name one release later
Before (v41)
users
type
notes
id
bigint
PK
email
text
unique
full_name
text
to split
created_at
timestamptz
During (steps 1–5)
users
type
notes
id
bigint
PK
email
text
unique
full_name
text
still written
first_name
text
nullable, new
last_name
text
nullable, new
created_at
timestamptz
After (v43)
users
type
notes
id
bigint
PK
email
text
unique
first_name
text
not null
last_name
text
not null
created_at
timestamptz
Every step is its own deploy
Each step rolls back on its own
Never rename in place: add, copy, switch, drop
SET lock_timeout = '5s' on every DDL
CREATE INDEX CONCURRENTLY on big tables
Zero-downtime schema migration
no
yes
The zero-downtime schema migration template as it opens in Kelvo: 8 boxes, 1 decision among them, 5 sticky notes, 3 tables and 8 links.

What's on the board

Rules
Every step is its own deploy · Each step rolls back on its own · Never rename in place: add, copy, switch, drop · SET lock_timeout = '5s' on every DDL · CREATE INDEX CONCURRENTLY on big tables

Table 1 columns: users, type, notes.

Table 2 columns: users, type, notes.

Table 3 columns: users, type, notes.

Also on the board

  • Fix the backfill, re-run
  • Counts + checksums match?
  • 1. Expand: add first_name, last_name (nullable)
  • 2. Deploy: write both old and new columns
  • 3. Backfill in batches of 10k rows
  • 6. Contract: drop full_name one release later
  • 5. Stop writing full_name
  • 4. Switch reads to new columns (flag)
  • Before (v41)
  • During (steps 1–5)
  • After (v43)

How to use this template

  1. Click Use this template. It opens in the Kelvo app as a new board, saved in your browser.
  2. Double-click any box to change its text. Replace the examples with your own content.
  3. Paste a table. Paste comma- or tab-separated text and it becomes a table. Tab moves to the next cell and adds rows as you go.
  4. Paste code as code. Paste a snippet and it becomes a code block with syntax colouring; Tab indents inside it.
  5. Link by dragging. Hover a box and drag one of its dots onto another box. The whole box is the target, and links stay attached when you move things.

Good for

  • database
  • migration
  • schema
  • zero downtime
  • engineer
  • Designing a schema or an API before writing it
  • Explaining a tricky flow in a code review or design doc
  • Agreeing on team conventions such as branching and reviews

Related templates

  • ER diagram (database schema) template previewER diagram (database schema)

    Entities as tables with columns, types and keys, joined by one-to-many relationships — sketch a schema before the migration.

  • UML class diagram template previewUML class diagram

    Classes with fields and methods, associations with multiplicity, and an interface with two implementations.

  • State machine template previewState machine

    Every state an order can be in and the events that move it — the source of truth for status logic and tests.

  • Sequence diagram (request flow) template previewSequence diagram (request flow)

    Numbered steps across Client, API gateway, service, database and a third party — how one checkout request really travels.

  • Git branching strategy template previewGit branching strategy

    Trunk-based development with short-lived feature branches, pull requests, release branches and a cherry-picked hotfix.

  • Strangler fig migration template previewStrangler fig migration

    Replace a legacy monolith slice by slice behind a routing facade, in three phases, with a tracker for each slice.

All software engineering diagram templates · All templates

Use the zero-downtime schema migration template