database-migrations

name	database-migrations
description	Use when: write and apply schema migrations safely without downtime or data loss.

Goal: schema changes that are reversible, ordered, and safe in production.

Use for:

• adding, altering, or dropping columns and tables
• coordinating schema and code deploys
• avoiding locks and data loss on large tables

Workflow:

1. Make each migration small, ordered, and version-controlled.
2. Prefer additive changes; split risky changes into steps.
3. Use expand-then-contract for renames and type changes.
4. Backfill data in batches to avoid long locks.
5. Deploy code that tolerates both old and new schema.
6. Verify on a production-like dataset before rollout.

Expand/contract:

• add new column/table, deploy dual-write code
• backfill, then switch reads
• remove old column only after nothing uses it

Rules:

• never edit an already-applied migration; add a new one
• avoid long-held locks on large tables
• make migrations reversible or document the rollback
• test against realistic data volume, not an empty schema