Skip to content

Document PERMISSION table handling in v4 migration guide #117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nscuro merged 1 commit into from
Jun 1, 2026
Merged

Document PERMISSION table handling in v4 migration guide #117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/guides/administration/migrating-from-v4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
nscuro marked this conversation as resolved.
Comment thread
nscuro marked this conversation as resolved.
Comment thread
nscuro marked this conversation as resolved.
Comment thread
nscuro marked this conversation as resolved.
Comment thread
nscuro marked this conversation as resolved.
Comment thread
nscuro marked this conversation as resolved.

### 2. Verify the target

Expand All @@ -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
Expand Down Expand Up @@ -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`.
Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/rehearsing-the-v4-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**.
Comment thread
nscuro marked this conversation as resolved.

## Verifying the empty target

Expand Down Expand Up @@ -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
Expand Down