# Schema Migration

> Procedure — schema migration

- Skill: `ai-driven-dev/schema-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ai-driven-dev/schema-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-driven-dev/schema-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ai-driven-dev (https://skillmd.com/u/ai-driven-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ai-driven-dev/schema-migration

---


# Procedure — schema migration

Two releases, never one. The rule exists because we took production down for
11 minutes in November doing it in one.

## Release N — additive only

1. Add the column, nullable, with no default. A default on a large table
   rewrites it.
2. Backfill in batches, out of band. Never in the migration itself.
3. Write to both old and new column. Read from the old one.

## Release N+1 — once the backfill is verified

4. Read from the new column. Keep writing to both.
5. Verify for one full week, with the metric that counts disagreements between
   the two.

## Release N+2

6. Stop writing to the old column.
7. Drop it.

## The check that must pass before each step

`SELECT count(*) FROM t WHERE new IS NULL AND old IS NOT NULL` returns 0.