[wolpert]

Summary

Hosts with their own identity model that excluded V5__example_users.sql failed on 2.3.0's V12__users_username_case_insensitive.sql with relation "users" does not exist. Example and library-owned migrations shared one flat location, so there was no clean opt-out.

The migrations now ship in two subdirectories sharing one version sequence:

Location	Contents	Required
classpath:db/migration/core	V1–V4, V6–V11 (tables pk-auth owns)	Always
classpath:db/migration/example-users	V5, V12 (example users table)	Only with JdbiUserLookup
classpath:db/migration	Both (Flyway scans recursively)	Alternative to listing both

File names and bytes are unchanged (sha256-verified), so Flyway checksums still match. V12 is not edited.

This deviates from the sibling-location layout (db/migration-example-users/) originally proposed. That layout would break hosts that use the example table via the documented classpath:db/migration: Flyway validation fails on applied-but-unresolved V5/V12. The nested layout keeps that documented configuration working unchanged, which is what makes this a patch release. ADR 0021 records the options.

API additions (PkAuthJdbiSchema, @since 2.3.1)

• MIGRATION_LOCATION, CORE_MIGRATION_LOCATION, EXAMPLE_USERS_MIGRATION_LOCATION
• CORE_SCHEMA_VERSION ("11"): Flyway refuses a target that no configured location resolves, so core-only hosts cannot target CURRENT_SCHEMA_VERSION ("12").
• migrateCoreForDevelopment(DataSource)

Host upgrade impact

• Flyway location classpath:db/migration (with or without the example table): no change.
• Scripts copied from the jar by pattern with V5 excluded: change db/migration/V*.sql to db/migration/core/V*.sql and drop the exclusion. The old pattern matches nothing and fails validation loudly. That pattern relied on the jar's internal resource layout, which was never documented.
• New core-only hosts: list classpath:db/migration/core, target CORE_SCHEMA_VERSION.

Full notes are in CHANGELOG.md and docs/operator-guide.md.

Tests

JdbiMigrationLocationsIntegrationTest (Testcontainers Postgres):

• core only on an empty database succeeds with no users table (regression test)
• core + example creates users and users_username_lower_key
• parent location resolves all 12; overlapping parent + subdirectory resolves each once
• a database built from the 2.3.0 flat layout validates against the split layout, and fails if the example location is dropped
• a database that excluded V5 (left at V11) upgrades with core only
• CORE_SCHEMA_VERSION matches the highest core migration on disk

Recursive scanning was also checked against the packaged jar (12 / 10 / 2 migrations resolved).

./gradlew check --rerun-tasks: 715 tests, 0 failures. Without --rerun-tasks, Spotless hit the known NoClassDefFoundError classloader issue on unchanged modules; a clean main worktree passed, so it is stale task state, not formatting. Playwright e2e suites were not run.

Release

Also retargets gradle.properties to 2.3.1-SNAPSHOT. Since v2.3.0, main carries only patch-level dependency bumps.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud