Jon Chery
53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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) | |