From 93275a73175014b9c18c228c52f3760dfd305334 Mon Sep 17 00:00:00 2001 From: nscuro Date: Mon, 1 Jun 2026 14:02:25 +0200 Subject: [PATCH] Document PERMISSION table handling in v4 migration guide Signed-off-by: nscuro --- docs/guides/administration/migrating-from-v4.md | 8 +++++--- docs/tutorials/rehearsing-the-v4-migration.md | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/guides/administration/migrating-from-v4.md b/docs/guides/administration/migrating-from-v4.md index ec714b8..f1db4b0 100644 --- a/docs/guides/administration/migrating-from-v4.md +++ b/docs/guides/administration/migrating-from-v4.md @@ -145,8 +145,8 @@ v4-migrator bootstrap \ --target-pass ``` -After this, the target has the v5 schema but no rows. -The migrator's later phases populate `PERMISSION`, `LICENSE`, `TEAM`, etc. directly from your v4 source. +After this, the target has the v5 schema and a seeded `PERMISSION` catalog (the well-known set of v5 permissions). +No other rows are written by bootstrap; the migrator's later phases populate `LICENSE`, `TEAM`, `USER`, and the rest from your v4 source. ### 2. Verify the target @@ -162,7 +162,7 @@ v4-migrator verify \ `verify` reads but never writes. On a freshly bootstrapped target with no staging present, expect: - Schema version `202605111028` reported `OK`. -- All row count columns zero. +- All row count columns **except for the v5 `PERMISSION` table** zero. - No probe entries. ### 3. Dry run @@ -505,6 +505,8 @@ v4-migrator bootstrap --target-url ... --target-user ... --target-pass v4-migrator load --target-url ... --target-user ... --target-pass ``` +`bootstrap` re-seeds the v5 `PERMISSION` catalog after applying the schema, so the rerun of `load` can resolve permission foreign keys without re-running `transform`. + !!! warning Don't manually `TRUNCATE` individual v5 tables and re-run `load`. diff --git a/docs/tutorials/rehearsing-the-v4-migration.md b/docs/tutorials/rehearsing-the-v4-migration.md index c9d7f82..bd120a4 100644 --- a/docs/tutorials/rehearsing-the-v4-migration.md +++ b/docs/tutorials/rehearsing-the-v4-migration.md @@ -147,7 +147,7 @@ Applying v5 Flyway schema up to 202605111028 Bootstrap complete. Flyway head = 202605111028. Run 'extract' or 'run' next. ``` -After this, the target has the v5 schema but no rows. +After this, the target has the v5 schema but no rows, **except in the `PERMISSION` table**. ## Verifying the empty target @@ -180,7 +180,7 @@ Expected output: 13 CHECK constraint(s) hold across 55 loaded table(s) ``` -If the schema version is anything else or any row count is non-zero, +If the schema version is anything else or any row count is non-zero, **except in the `PERMISSION` table**, the rest of the rehearsal will not work. ## Dry-running the migration