atelier/domains/data/migrations.md

Migrations — Derived Rules

Derives from domains/data/first-principles.md P4 (Migration Safety), P5 (Reversibility via core C5).

Every Change is a Migration (P4)

• No manual schema changes. No ALTER TABLE in a shell. Every change is a versioned migration file.
• Migrations are code: reviewed, tested, committed.
• The migration tool is the only way to change the schema (prisma migrate, alembic, flyway, golang-migrate).

Forward and Reverse (P5 Reversibility, core C5)

• Every migration has an up and a down. The down reverses the up.
• A migration without a down is irreversible. Irreversible migrations are rare and flagged.
• Test the down in CI. A down that fails is a migration that cannot be rolled back.

Expand, Migrate, Contract (P5)

For non-breaking schema changes:

1. Expand: add the new column/ table (nullable, no constraint). Deploy. Old code still works.
2. Migrate: backfill data, run the data migration. Deploy. Both old and new code work.
3. Contract: add constraints, remove the old column. Deploy after all code uses the new schema.

Never do all three in one migration. Each step is its own deploy.

Avoid Destructive Changes (P4)

• Never DROP COLUMN in a migration that could be in use. Expand-contract first.
• Never DROP TABLE without confirming no code references it.
• Never ALTER TYPE in a way that locks the table on a large dataset. Use a phased approach.

Backward Compatibility (P5, P1)

• A migration must not break the running code. Old code reads the new schema (with expand).
• The schema is always compatible with the previous code version. Two-version compatibility.
• A breaking migration is deployed in lockstep with the code, with a maintenance window.

Testing Migrations (P3 Determinism via testing P3)

• Run migrations on a copy of production data in CI. A migration that works on dev may fail on prod scale.
• Test the down on the migrated state, not just the up.
• Test with the largest table sizes you have. ALTER TABLE on 10 rows is fast; on 10M rows, it may lock.

What Violates Migration Safety

Violation	Principle
Manual ALTER TABLE in prod	P4
Migration with no down	P5 Reversibility
DROP COLUMN in the same deploy as the new code	P4, P5
No migration test on prod-scale data	P3 Determinism
A migration that locks a table for 10 minutes	P4 (downtime)