fix: Liquibase coexistence + NCDF on Spring Boot 3.5.x without liquibase-core (KOJAK-80) (#42)

## Summary

Closes GitHub issue #38 and JIRA KOJAK-80. Also fixes a related
undocumented `NoClassDefFoundError` that prevented startup on Spring
Boot 3.5.x consumers without `liquibase-core` on the classpath (e.g.
Flyway-only users) — discovered during the work.

### NCDF guard — fix for the related startup bug
- Move `okapi*Liquibase` factory methods into dedicated
`PostgresLiquibaseConfiguration` / `MysqlLiquibaseConfiguration` inner
classes with class-level `@ConditionalOnClass(SpringLiquibase)`. Spring
evaluates the class-level condition via string-name lookup **before**
any method introspection, so `Class.getDeclaredMethods()` is never
called on a class whose `SpringLiquibase` return type would trigger
`NoClassDefFoundError`.

### Issue #38 Mode 1 / KOJAK-80 §1 — host's `liquibase` bean shadowed
- Add `@AutoConfigureAfter(name = [3.x path, 4.x path])` on
`OutboxAutoConfiguration` so Spring Boot's `LiquibaseAutoConfiguration`
registers its own `liquibase` bean first. Without this, okapi's
`okapiPostgresLiquibase` (typed `SpringLiquibase`) shadows Spring Boot's
type-based `@ConditionalOnMissingBean(SpringLiquibase)` guard, silently
suppressing the host application's own changelog.
- **Decision re. ordering direction**: KOJAK-80 suggested
`@AutoConfigureBefore` as the leading candidate. The PR uses
`@AutoConfigureAfter` — `Before` would put okapi's bean first and
trigger the exact shadowing it's meant to prevent (Spring Boot's
`@ConditionalOnMissingBean(SpringLiquibase)` is type-based and would
skip its own bean if okapi's is registered first). Rationale documented
in the KDoc and the JIRA comment on KOJAK-80.
- **No `@DependsOn` KDoc**: KOJAK-80 also asked for a note about host
beans declaring `@DependsOn("okapiPostgresLiquibase")` to handle FKs
into `okapi_outbox`. That motivating case is an anti-pattern (the purger
needs to delete `okapi_outbox` rows; a host FK would block it and stall
the queue) — documenting it would encourage misuse. The 99.999% of users
whose changelogs don't reference okapi's tables get a working setup with
no extra ceremony. Decision logged on KOJAK-80.
- Keep `@ConditionalOnMissingBean(name = ...)` (not type-based) so
user-supplied `@Bean SpringLiquibase liquibase()` coexists with okapi's
bean, while `@Bean("okapiPostgresLiquibase")` still cleanly overrides
okapi's default.

### Opt-out
- New `okapi.liquibase.enabled` property (default `true`) for explicit
opt-out when the host app includes okapi's changelog from its own master
changelog.
- New `LiquibaseDisabledNotice` inner config logs a WARN-level
breadcrumb on `enabled=false`, linking a future *"relation okapi_outbox
does not exist"* runtime error back to the startup decision.

## Test plan

Adopts the testing pattern PR #41 introduced for the analogous
Micrometer ordering bug (real Spring Boot autoconfig + reflection
meta-test).

- **Real autoconfig coexistence E2E** (Postgres + MySQL): pulls Spring
Boot's `LiquibaseAutoConfiguration` via `resolveSpringBootClass(...)`,
sets `spring.liquibase.change-log`, asserts both beans register and both
changelogs run.
- **Multi-DataSource E2E** (KOJAK-80 §2): two real Postgres containers,
`okapi.datasource-qualifier=secondaryDs`, asserts `okapi_outbox` lands
on the secondary and not the primary.
- **Structural pins** (`LiquibaseAutoConfigurationTest`):
- No `SpringLiquibase` return type on `OutboxAutoConfiguration` /
`PostgresStoreConfiguration` / `MysqlStoreConfiguration` (NCDF guard
would otherwise return).
- Class-level `@ConditionalOnClass(SpringLiquibase)` on both new
Liquibase configs.
- Name-based `@ConditionalOnMissingBean` (type-based would re-introduce
Mode 1).
- `@AutoConfigureAfter` annotation is structurally sound; declared names
resolve when Spring Boot Liquibase autoconfig is on classpath.
- **Log capture**: `LiquibaseDisabledNotice` WARN message captured via
logback `ListAppender` — deletion of the warn body breaks the test, not
just deletion of the class.
- **User override**: end-to-end test for
`@Bean("okapiPostgresLiquibase")` taking precedence over okapi's
default.

### Verified
- [x] `./gradlew :okapi-spring-boot:test` — Spring Boot 4.0.6 (default)
- [x] `./gradlew :okapi-spring-boot:test -PspringBootVersion=3.5.12
-PspringVersion=6.2.17`
- [x] `./gradlew :okapi-spring-boot:ktlintCheck`
- [x] Sanity-checked four likely regressions — each fails a distinct
test in the new suite:
  - Remove 3.x `@AutoConfigureAfter` path → meta-test failure on 3.5.12
- Remove `@AutoConfigureAfter` entirely → unconditional structural check
failure
  - Switch to type-based `@ConditionalOnMissingBean` → name-pin failure
- Move Liquibase bean back into `PostgresStoreConfiguration` → NCDF
structural guard failure
- [x] Empirically verified on `okapi-autocomplete-test` (Spring Boot
3.5.7, no `liquibase-core` on classpath) — app starts cleanly; the
original `NoClassDefFoundError` is gone.

Author: endrju19

README.md

@@ -99,7 +99,7 @@ Okapi implements the [transactional outbox pattern](https://softwaremill.com/mic
 
 Okapi ships Liquibase changelogs that create the outbox table and its indexes:
 
-- `classpath:com/softwaremill/okapi/db/changelog.xml` — PostgreSQL (from `okapi-postgres`)
+- `classpath:com/softwaremill/okapi/db/postgres/changelog.xml` — PostgreSQL (from `okapi-postgres`)
 - `classpath:com/softwaremill/okapi/db/mysql/changelog.xml` — MySQL (from `okapi-mysql`)
 
 When `okapi-spring-boot` is on the classpath, these run automatically against the configured `DataSource` on application startup. Without Spring Boot, point your own Liquibase setup at the paths above and pass an `outboxTable` change-log parameter (see below).
@@ -273,7 +273,7 @@ Throughput baseline (single instance, sync sequential delivery, MacBook M3 Max,
 | HTTP @ webhook latency 20 ms | ~33 msg/s | ~36 msg/s |
 | HTTP @ webhook latency 100 ms | ~9 msg/s | ~9 msg/s |
 
-These numbers reflect the current sync-sequential delivery model. Throughput is bounded by per-message round-trip time × batch size. Performance work to lift these limits (async batch delivery, multi-threaded scheduler) is tracked under the [KOJAK-14 epic](https://softwaremill.atlassian.net/browse/KOJAK-14).
+These numbers reflect the current sync-sequential delivery model. Throughput is bounded by per-message round-trip time × batch size.
 
 Full methodology, raw JMH results, and reproduction instructions: [`benchmarks/`](benchmarks/).
 

gradle/libs.versions.toml

@@ -14,6 +14,7 @@ springBoot = "4.0.6"
 vanniktechPublish = "0.36.0"
 wiremock = "3.13.2"
 slf4j = "2.0.18"
+logback = "1.5.20"
 assertj = "3.27.7"
 h2 = "2.4.240"
 micrometer = "1.16.5"
@@ -53,6 +54,7 @@ micrometerTest = { module = "io.micrometer:micrometer-test", version.ref = "micr
 wiremock = { module = "org.wiremock:wiremock", version.ref = "wiremock" }
 slf4jApi = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
 slf4jSimple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }
+logbackClassic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
 h2 = { module = "com.h2database:h2", version.ref = "h2" }
 jmhCore = { module = "org.openjdk.jmh:jmh-core", version.ref = "jmh" }
 jmhGeneratorAnnprocess = { module = "org.openjdk.jmh:jmh-generator-annprocess", version.ref = "jmh" }

okapi-benchmarks/src/jmh/kotlin/com/softwaremill/okapi/benchmarks/support/PostgresBenchmarkSupport.kt

@@ -47,7 +47,7 @@ class PostgresBenchmarkSupport {
     private fun runLiquibase() {
         val connection = DriverManager.getConnection(container.jdbcUrl, container.username, container.password)
         val db = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(JdbcConnection(connection))
-        Liquibase("com/softwaremill/okapi/db/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
+        Liquibase("com/softwaremill/okapi/db/postgres/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
         connection.close()
     }
 }

okapi-integration-tests/src/test/kotlin/com/softwaremill/okapi/test/support/PostgresTestSupport.kt

@@ -40,7 +40,7 @@ class PostgresTestSupport {
     private fun runLiquibase() {
         val connection = DriverManager.getConnection(container.jdbcUrl, container.username, container.password)
         val db = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(JdbcConnection(connection))
-        Liquibase("com/softwaremill/okapi/db/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
+        Liquibase("com/softwaremill/okapi/db/postgres/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
         connection.close()
     }
 }

okapi-integration-tests/src/test/kotlin/com/softwaremill/okapi/test/transaction/ConnectionLeakProofTest.kt

@@ -105,6 +105,6 @@ class ConnectionLeakProofTest : FunSpec({
 private fun runLiquibase(container: PostgreSQLContainer<Nothing>) {
     DriverManager.getConnection(container.jdbcUrl, container.username, container.password).use { connection ->
         val db = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(JdbcConnection(connection))
-        Liquibase("com/softwaremill/okapi/db/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
+        Liquibase("com/softwaremill/okapi/db/postgres/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
     }
 }

okapi-integration-tests/src/test/kotlin/com/softwaremill/okapi/test/transaction/MultiDataSourceTransactionTest.kt

@@ -139,6 +139,6 @@ class MultiDataSourceTransactionTest : FunSpec({
 private fun runLiquibase(container: PostgreSQLContainer<Nothing>) {
     val connection = DriverManager.getConnection(container.jdbcUrl, container.username, container.password)
     val db = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(JdbcConnection(connection))
-    Liquibase("com/softwaremill/okapi/db/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
+    Liquibase("com/softwaremill/okapi/db/postgres/changelog.xml", ClassLoaderResourceAccessor(), db).use { it.update("") }
     connection.close()
 }