Database Migration Patterns

Safe, reversible database schema changes for production systems.

When to Activate

• Creating or altering database tables, columns, or indexes
• Running data migrations (backfill, transform)
• Planning zero-downtime schema changes
• Setting up migration tooling for a new project
• User asks for "migration", "schema change", or "database change"

Core Principles

1. Every change is a migration — Never alter production databases manually; always use versioned migration files.
2. Migrations are forward-only in production — Rollbacks use new forward migrations, not editing old ones.
3. Schema and data migrations are separate — Do not mix DDL and large DML in one migration; split so rollback and testing are clear.
4. Test against production-sized data — A migration that works on 100 rows may lock or time out on 10M.
5. Migrations are immutable once deployed — Never edit a migration that has already run in production; add a new migration instead.