Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
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) | |