diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## 0.2.0.0 — 2026-07-30 + +### Breaking Changes + +- Raised `keiro-migrations` to `^>=0.4.0.1`. Keiro's component gains two migrations, which the + composed `kiokuMigrationPlan` now carries: + `0019-keiro-snapshots-state-shape-hash.sql`, which adds a `state_shape_hash` column to + `keiro.keiro_snapshots`, and `0020-keiro-workflow-children-failure-reason.sql`, which adds a + nullable `failure_reason` column to Keiro's workflow-children table. Both are additive + `ALTER TABLE ... ADD COLUMN` statements on Keiro-owned tables that Kioku neither reads nor + writes. The plan's forward-migration total moves from 36 to 38. + +### Deprecated + +- `Kioku.Migrations.History.Codd` and the `codd-upgrade/` SQL fixups are deprecated. They are a + one-time bridge for databases whose schema evolution predates the pg-migrate cutover; a database + created by `kioku-migrate up` has never needed them. Removal is gated on the last codd-era + downstream database crossing over — as of this release that is Shikigami, tracked by its + `docs/plans/38-migrate-shikigami-database-evolution-from-codd-to-pg-migrate.md`. If you still + have a `codd.sql_migrations` table, cross over now: the bridge will be deleted, together with + everything listed in `codd-upgrade/README.md`, in a future release. + ## 0.1.0.0 — 2026-07-14 ### Added diff --git a/codd-upgrade/README.md b/codd-upgrade/README.md --- a/codd-upgrade/README.md +++ b/codd-upgrade/README.md @@ -20,3 +20,32 @@ The Kioku migration rehearsal executes these same files. See `docs/user/upgrading-to-pg-migrate.md` for the complete backup, import, forward-migration, and verification procedure. + +## Deprecated: scheduled for removal + +This directory and everything that reads it are **deprecated as of kioku 0.2.0.0**. They exist +only as a one-time bridge for databases whose schema evolution predates the pg-migrate cutover +(kioku ExecPlan 20). A database created by `kioku-migrate up` has never needed any of it. + +**The removal gate.** Removal is blocked on the last codd-era downstream database crossing over. +As of 2026-07-30 that is Shikigami, which still declares `codd >=0.1.8 && <0.2` and `codd-extras`, +still Git-pins `hasql-migration` and `codd-project`, and still pins Kioku at the pre-pg-migrate +commit `8bcfc282484dd59b0a0b25530cca4f3ad9034ce1`. Its crossing is tracked by Shikigami's +`docs/plans/38-migrate-shikigami-database-evolution-from-codd-to-pg-migrate.md`. + +Before removing, confirm no live database still has a `codd.sql_migrations` table. A migration +ledger is forward-only — there is no unapply — so deleting the bridge early strands such a +database with no supported route across. + +**Remove these together, in one commit:** + +- this directory, `kioku-migrations/codd-upgrade/`, and its `extra-doc-files` / + `extra-source-files` entries +- `kioku-migrations/src/Kioku/Migrations/History/Codd.hs` +- the `import` subcommand and its options parser in `kioku-migrate/app/Main.hs` +- the `pg-migrate-import-codd` dependency from `kioku-migrations.cabal` (library *and* + test-suite stanzas) and from `kioku-migrate.cabal` +- `testCoddCohortImport` in `kioku-migrations/test/Main.hs`, with its fixture + `kioku-migrations/test/fixtures/pre-cutover-schema.sql` and the `coddV5Ledger` and + `coddSnapshotStatement` helpers +- the `.claude/skills/cohort-migrate` skill, which is built entirely on this bridge diff --git a/kioku-migrations.cabal b/kioku-migrations.cabal --- a/kioku-migrations.cabal +++ b/kioku-migrations.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: kioku-migrations -version: 0.1.0.0 +version: 0.2.0.0 synopsis: Schema migrations for kioku description: Owns kioku schema evolution as a native pg-migrate component and composes @@ -58,7 +58,7 @@ , containers >=0.6 && <0.8 , hasql >=1.10 && <1.11 , hasql-transaction >=1.2 && <1.3 - , keiro-migrations ^>=0.3.0.0 + , keiro-migrations ^>=0.4.0.1 , kiroku-store-migrations ^>=0.3.0.0 , pg-migrate ^>=1.1.0.0 , pg-migrate-embed ^>=1.1.0.0 @@ -75,7 +75,7 @@ , base >=4.18 && <5 , ephemeral-pg ^>=0.2.2.0 , hasql >=1.10 && <1.11 - , kioku-migrations ^>=0.1.0.0 + , kioku-migrations ^>=0.2.0.0 , pg-migrate-test-support ^>=1.1.0.0 , text >=2.0 && <2.2 @@ -84,11 +84,14 @@ type: exitcode-stdio-1.0 main-is: Main.hs hs-source-dirs: test - ghc-options: -threaded -rtsopts -with-rtsopts=-N + + -- testCoddCohortImport rehearses the deprecated codd import bridge on purpose; + -- the bridge must keep working until the last codd-era database crosses over. + ghc-options: -threaded -rtsopts -with-rtsopts=-N -Wno-deprecations build-depends: , base >=4.18 && <5 , hasql >=1.6 - , kioku-migrations ^>=0.1.0.0 + , kioku-migrations ^>=0.2.0.0 , kioku-migrations:test-support , pg-migrate ^>=1.1.0.0 , pg-migrate-embed ^>=1.1.0.0 diff --git a/src/Kioku/Migrations/History/Codd.hs b/src/Kioku/Migrations/History/Codd.hs --- a/src/Kioku/Migrations/History/Codd.hs +++ b/src/Kioku/Migrations/History/Codd.hs @@ -1,7 +1,18 @@ {-# LANGUAGE MultilineStrings #-} {-# LANGUAGE TemplateHaskell #-} +-- | +-- One-time bridge for databases whose schema evolution was applied by codd +-- before Kioku moved to pg-migrate. It maps the historical 30-migration codd +-- cohort onto pg-migrate's ledger so an existing database crosses over without +-- replaying any DDL. It is not part of the ongoing migration path: a database +-- created by @kioku-migrate up@ has never needed it. module Kioku.Migrations.History.Codd + {-# DEPRECATED + "One-time codd import bridge. Scheduled for removal once Shikigami plan 38 \ + \completes its codd-to-pg-migrate cutover; a database created by kioku-migrate \ + \has never needed this module." + #-} ( kiokuCoddHistoryMappings, cohortCoddHistoryMappings, cohortCoddSourceConfig, diff --git a/test/Main.hs b/test/Main.hs --- a/test/Main.hs +++ b/test/Main.hs @@ -74,7 +74,7 @@ testCase "the full migration chain applies to a fresh database" testFreshDatabase, testCase "the migration manifest is complete and valid" testManifestIntegrity, testCase "the pinned Codd history maps 30 known plan targets" testHistoryMappings, - testCase "the pre-cutover Codd cohort imports 30 rows and applies only six forward migrations" testCoddCohortImport + testCase "the pre-cutover Codd cohort imports 30 rows and applies only eight forward migrations" testCoddCohortImport ] -- * The manifest guard @@ -265,13 +265,13 @@ verification <- verifyMigrationPlan defaultRunOptions settings plan >>= either (assertFailure . show) pure let VerificationReport {issues = verificationIssues, appliedMigrations, pendingMigrations, unknownMigrations} = verification verificationIssues @?= [] - length appliedMigrations @?= 36 + length appliedMigrations @?= 38 pendingMigrations @?= [] unknownMigrations @?= [] repeated <- runMigrationPlan defaultRunOptions settings plan >>= either (assertFailure . show) pure let MigrationReport {results = repeatedResults} = repeated - length [() | MigrationResult {outcome = AlreadyApplied} <- toList repeatedResults] @?= 36 + length [() | MigrationResult {outcome = AlreadyApplied} <- toList repeatedResults] @?= 38 length [() | MigrationResult {outcome = AppliedNow} <- toList repeatedResults] @?= 0 fixtureMigrationNames :: Text -> [FilePath] @@ -342,7 +342,9 @@ migrationId "keiro" "0015-keiro-outbox-claim-order-index", migrationId "keiro" "0016-keiro-inbox-drop-received-idx", migrationId "keiro" "0017-schema-management-comment", - migrationId "keiro" "0018" + migrationId "keiro" "0018", + migrationId "keiro" "0019-keiro-snapshots-state-shape-hash", + migrationId "keiro" "0020-keiro-workflow-children-failure-reason" ] expectRight :: (Show error) => Either error value -> value