coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity
Files
4e433158cd80a34dde592be3306aeb4dcc42c191
atelier/domains/data/migrations.md
T
Jon Chery 496303471d docs(milestone): complete v0.1 — initial framework 
---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.
2026-08-05 00:36:55 +00:00

2.4 KiB
Raw Blame History

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)
Reference in New Issue View Git Blame Copy Permalink