ADR 0011 — Capabilities own migration progress

ADR 0011 — Capabilities own migration progress An architecture diagram generated by Archify. Capabilities own migration progress · (owner, version) history · no global version ranges · Architecture component Capabilities own migration progress (owner, version) history · no global version ranges app.MigrationSources(mods) · the foundation first, then each Migrations fs in order · the mechanism app.MigrationSources(mods) the foundation first, then each Migrations fs in order db.Migrate · db.MigrationSource · pg_advisory_lock · one tx per file with its history row · the mechanism db.Migrate · db.MigrationSource pg_advisory_lock · one tx per file with its history row <version>_<name>.up.sql per owner · embedded per owner · numeric order · no down files · the mechanism <version>_<name>.up.sql per owner embedded per owner · numeric order · no down files kit/db/migrate_test.go · independent owners · retry · append-only history · kept true by kit/db/migrate_test.go independent owners · retry · append-only history Rejected: one global ledger and down files · at 2003, new public 23 or catalog 1001 was skipped · Architecture component Rejected: one global ledger and down files at 2003, new public 23 or catalog 1001 was skipped the private catalog and clients · module name owns the history · versions local to it · Architecture component the private catalog and clients module name owns the history · versions local to it every role at boot · App.Run migrates first, web, worker and all alike · Architecture component every role at boot App.Run migrates first, web, worker and all alike listed by applied by numbered in checked by instead of passes the composition at boot ship SQL under their own name the mechanism kept true by Legend Backend Database Security External

Context

  • • Before: one scalar version for the whole composition, a (version, dirty) ledger, a flattened filesystem and down files
  • • A composed client at 2003 gained public 23 or catalog 1001 with success reported while the new SQL was silently skipped

Consequences

  • • Each owner advances alone under one advisory lock; a changed, missing or inserted-before file fails before any SQL runs; an omitted owner keeps its data
  • • A fresh baseline: no ledger conversion, a clean database, applied files stay unchanged, and a downgraded image is not a schema rollback

Evidence

  • • go test ./kit/db -run TestMigrationOwnersAdvanceIndependently, and the failure/retry, append-only, concurrent and cancellation cases beside it
  • • go test ./kit/app -run TestMigrationSourcesFollowComposition boots a real application; the runner is no SQL parser or sandbox