diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.7.1.0 — 2026-10-11 + +### New Features + +- Migration 0015 adds one partial byte-ordered name index for catalog and literal-prefix + reads, preserving existing unique-name and category/event indexes. The transactional + build requires a write pause on large stores; write-cost evidence and its limitations are recorded + by MasterPlan 13. The inspection cohort received practical performance acceptance before publication. + + ## 0.7.0.0 — 2026-10-10 ### Breaking Changes diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ `kiroku-store-migrations` owns Kiroku's PostgreSQL schema as one native `pg-migrate` component named `kiroku`. The component embeds an ordered manifest -and twelve SQL payloads, so applications can compose it with other libraries +and fifteen SQL payloads, so applications can compose it with other libraries without copying Kiroku SQL. The first seven payloads are immutable historical -Codd bytes; `0008` through `0012` are native-only forward migrations. +Codd bytes; `0008` through `0015` are native-only forward migrations. ## Public API diff --git a/kiroku-store-migrations.cabal b/kiroku-store-migrations.cabal --- a/kiroku-store-migrations.cabal +++ b/kiroku-store-migrations.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: kiroku-store-migrations -version: 0.7.0.0 +version: 0.7.1.0 synopsis: Schema migrations for kiroku-store description: Native pg-migrate component, Codd history mapping, and migration executable diff --git a/migrations/0015.sql b/migrations/0015.sql new file mode 100644 --- /dev/null +++ b/migrations/0015.sql @@ -0,0 +1,16 @@ +-- Stable byte-ordered stream catalog browsing (MasterPlan 13 / plan 88). +-- The original unique-name constraint and category index remain unchanged. +-- This one browse index also serves literal prefixes and exact-category ranges; +-- plan 54's bounded global-event windows require no separate prefix index. +-- PostgreSQL applies this transactional index build once. It blocks writes for +-- the build duration; schedule the upgrade in a maintenance window on large +-- stores. New-stream inserts and non-HOT application-stream updates pay its +-- maintenance cost. The reserved global stream is outside this partial index. +CREATE INDEX ix_streams_browse_name + ON kiroku.streams (stream_name COLLATE "C") + WHERE stream_id <> 0; + +COMMENT ON INDEX kiroku.ix_streams_browse_name IS + 'Byte-ordered stream browsing and literal-prefix seeks; does not change unique-name or subscription event ordering.'; +COMMENT ON SCHEMA kiroku IS + 'Managed by pg-migrate component kiroku through 0015'; diff --git a/migrations/manifest b/migrations/manifest --- a/migrations/manifest +++ b/migrations/manifest @@ -12,3 +12,4 @@ 0012.sql 0013.sql 0014.sql +0015.sql diff --git a/test/Main.hs b/test/Main.hs --- a/test/Main.hs +++ b/test/Main.hs @@ -44,7 +44,7 @@ main :: IO () main = hspec $ do describe "native Kiroku migration definition" $ do - it "tracks the fourteen native files in manifest order" $ do + it "tracks the fifteen native files in manifest order" $ do directory <- findMigrationsDirectory manifest <- Text.lines <$> Text.IO.readFile (directory "manifest") manifest `shouldBe` Text.pack <$> nativeMigrationFiles @@ -57,7 +57,7 @@ bytes <- ByteString.readFile (directory nativeName) lookup legacyName lockEntries `shouldBe` Just (checksumText bytes) - it "builds component kiroku and a fourteen-migration plan" $ do + it "builds component kiroku and a fifteen-migration plan" $ do component <- requireRight kirokuMigrations component `seq` pure () plan <- requirePlan @@ -93,7 +93,7 @@ `shouldReturn` "0007-existing.sql\n" describe "fresh native databases" $ do - it "applies all fourteen, verifies strictly, and reports AlreadyApplied on rerun" $ do + it "applies all fifteen, verifies strictly, and reports AlreadyApplied on rerun" $ do plan <- requirePlan result <- withMigratedDatabase plan $ \connection -> do assertSchema connection @@ -341,7 +341,7 @@ withConnection settings $ \connection -> useSession connection (Session.script "INSERT INTO kiroku.subscriptions (subscription_name, consumer_group_member, last_seen) VALUES ('group', 0, 5), ('group', 1, 20), ('incomplete', 0, 8), ('ordinary', 0, 10)") upgraded <- runMigrationPlan defaultRunOptions settings plan >>= requireMigration - reportOutcomes upgraded `shouldBe` replicate 12 AlreadyApplied <> replicate 2 AppliedNow + reportOutcomes upgraded `shouldBe` replicate 12 AlreadyApplied <> replicate (length nativeMigrationFiles - 12) AppliedNow withConnection settings $ \connection -> do let stmt = Statement.preparable @@ -462,7 +462,7 @@ pendingIds <- traverse (requireRight . migrationId "kiroku") - ["0008-schema-management-comment", "0009", "0010", "0011", "0012", "0013", "0014"] + ["0008-schema-management-comment", "0009", "0010", "0011", "0012", "0013", "0014", "0015"] verifiedBeforeCanary <- verifyMigrationPlan defaultRunOptions settings plan >>= requireMigration case verifiedBeforeCanary of VerificationReport verificationIssues _ _ _ -> @@ -503,6 +503,7 @@ , "0012.sql" , "0013.sql" , "0014.sql" + , "0015.sql" ] {- | The plan truncated to its first @count@ migrations, read from the checked-in @@ -646,7 +647,8 @@ (EXISTS (SELECT 1 FROM pg_catalog.pg_constraint WHERE conname = 'ck_stream_events_all_category')), (EXISTS (SELECT 1 FROM pg_catalog.pg_constraint WHERE conname = 'chk_streams_stream_name_length')), (EXISTS (SELECT 1 FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'kiroku' AND c.relname = 'streams' AND a.attname = 'truncate_before' AND NOT a.attisdropped)), - (obj_description(to_regnamespace('kiroku'), 'pg_namespace') = 'Managed by pg-migrate component kiroku through 0012') + (EXISTS (SELECT 1 FROM pg_catalog.pg_indexes WHERE schemaname = 'kiroku' AND indexname = 'ix_streams_browse_name' AND indexdef LIKE '%COLLATE "C"%' AND indexdef LIKE '%WHERE (stream_id <> 0)%')), + (obj_description(to_regnamespace('kiroku'), 'pg_namespace') = 'Managed by pg-migrate component kiroku through 0015') ) AS checks(ok) """ Encoders.noParams