Kora Database Migration

Kora Database Migration — Flyway and Liquibase

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Both modules are optional add-ons to the JDBC module. Neither has a Cassandra counterpart — migrations attach to the JDBC datasource only.

1. How migrations run — the interceptor, not a lifecycle hook

FlywayJdbcDatabaseModule contributes exactly one thing to the graph: a FlywayJdbcDatabaseInterceptor implements GraphInterceptor<JdbcDataSource>. At compile time the @KoraApp processor matches every GraphInterceptor<T> component against the nodes of type T and wires it into the generated graph. At runtime the graph calls afterInit(dataSource) after JdbcDataSource.init() has opened and validated the pool, and before any component that depends on the datasource is constructed. Liquibase works identically.

Three consequences that drive every decision below:

1. Migrations block startup. They run inside graph initialization, so the service is not listening and not ready until the migration finishes. A migration failure surfaces as a graph initialization error and the application exits.
2. Every replica migrates. The interceptor is attached per graph, so a horizontally scaled deployment runs it once per pod on every rollout — see §6.
3. The interceptor needs pool capacity. Flyway takes two connections (migration + schema history lock); Liquibase takes one. jdbc.maxPoolSize = 1 deadlocks an in-app Flyway migration at startup with no error message — the framework's own Flyway test pins the pool at 2 for exactly this reason.

Nothing else is required: no @Root, no ordering config, no explicit module method. Plugging the module in is the whole wiring.

2. Quick start — Flyway

1. Dependencies. Kora artifacts inherit their version from io.koraframework:kora-bom. The dialect artifact does not — kora-bom only constrains Kora's own modules, so it carries an explicit version.

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")   // koraVersion=2.0.0.RC1
    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:database-jdbc"
    implementation "io.koraframework:database-flyway"
    // Since Flyway 10 per-database support lives in separate artifacts and
    // database-flyway ships only flyway-core: without this the app dies at
    // startup with "FlywayException: Unsupported Database: PostgreSQL 16.2".
    implementation "org.flywaydb:flyway-database-postgresql:13.3.0"

    runtimeOnly "org.postgresql:postgresql:42.7.13"
}

Kotlin — same coordinates, ksp("io.koraframework:symbol-processors") instead of the annotation processor:

dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")

    implementation("io.koraframework:database-jdbc")
    implementation("io.koraframework:database-flyway")
    implementation("org.flywaydb:flyway-database-postgresql:13.3.0")

    runtimeOnly("org.postgresql:postgresql:42.7.13")
}

Pick the dialect artifact for your database (flyway-database-postgresql, flyway-mysql, flyway-database-oracle, …) and pin it to the same version as the flyway-core that database-flyway brings in — 13.3.0 for Kora 2.0.0.RC1. Verify with ./gradlew dependencies --configuration runtimeClasspath | grep flyway.

2. Plug both modules into @KoraApp. FlywayJdbcDatabaseModule supplies only the interceptor; the datasource still comes from JdbcDatabaseModule.

import io.koraframework.application.graph.KoraApplication;
import io.koraframework.common.annotation.KoraApp;
import io.koraframework.config.hocon.HoconConfigModule;
import io.koraframework.database.flyway.FlywayJdbcDatabaseModule;
import io.koraframework.database.jdbc.JdbcDatabaseModule;

@KoraApp
public interface Application extends
        HoconConfigModule,
        JdbcDatabaseModule,
        FlywayJdbcDatabaseModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

@KoraApp
interface Application :
    HoconConfigModule,
    JdbcDatabaseModule,
    FlywayJdbcDatabaseModule

fun main() {
    KoraApplication.run(ApplicationGraph::graph)
}

3. Migration script at src/main/resources/db/migration/V1__setup_tables.sql:

CREATE TABLE IF NOT EXISTS categories (
    id   BIGINT  NOT NULL GENERATED ALWAYS AS IDENTITY,
    name VARCHAR NOT NULL,
    PRIMARY KEY (id)
);

CREATE TABLE IF NOT EXISTS pets (
    id          BIGINT   NOT NULL GENERATED ALWAYS AS IDENTITY,
    name        VARCHAR  NOT NULL,
    status      SMALLINT NOT NULL,
    category_id BIGINT   NOT NULL REFERENCES categories(id),
    PRIMARY KEY (id)
);

4. Configure application.conf. The JDBC section is jdbc in Kora 2.0 — it was db in 1.x, and a leftover db { } block fails startup with ConfigValueException: Config expected value, but got null at path: 'ROOT.jdbc.username'.

jdbc {
  jdbcUrl  = ${POSTGRES_JDBC_URL}
  username = ${POSTGRES_USER}
  password = ${POSTGRES_PASS}
  poolName = "my-service"
  maxPoolSize = 10          // must be >= 2 while in-app Flyway migration runs
}

flyway {
  locations = "db/migration"
}

Every FlywayConfig and LiquibaseConfig key has a default and both are declared @ConfigMapper with mapNullAsEmptyObject = true, so the section itself is optional — a module with no flyway { } block migrates db/migration with defaults.

3. Flyway configuration

The complete FlywayConfig surface — these seven keys are all that exists:

flyway {
  enabled              = true              // run on startup; false skips migration entirely
  mode                 = MIGRATE           // MIGRATE | REPAIR | CLEAN_MIGRATE (exact case)
  locations            = ["db/migration"]  // classpath dirs holding V*.sql
  executeInTransaction = true              // wrap each migration in a transaction
  validateOnMigrate    = true              // verify checksums of applied scripts first
  mixed                = false             // allow transactional + non-transactional in one run
  configurationProperties { }              // raw flyway.* properties, flat quoted keys
}

• mode is new in Kora 2.0 and is matched exactly, uppercase. mode = migrate fails with Unknown enum value: migrate when expected one of [MIGRATE, REPAIR, CLEAN_MIGRATE]. CLEAN_MIGRATE drops the schema before migrating — a local/test convenience, never production.

• locations accepts either a HOCON array or a single comma-separated string; the migrated guide apps use the string form (locations = "db/migration").

• mixed = true is for statements that cannot run in a transaction (CREATE INDEX CONCURRENTLY on PostgreSQL, and equivalents on Aurora PostgreSQL, SQL Server, SQLite). The whole run then executes without a transaction.

• configurationProperties maps to Flyway.configure().configuration(Map), whose keys are Flyway's own flyway.-prefixed property names. Kora maps it as a flat Map<String, String>, so the dotted key must be quoted — unquoted, HOCON nests it and the config mapper throws:

  flyway {
    configurationProperties {
      "flyway.defaultSchema"    = "public"
      "flyway.baselineOnMigrate" = "true"
    }
  }
  

Full details — script naming, multiple locations, checksum recovery, testing — references/flyway-migration-reference.md.

4. Liquibase configuration

LiquibaseConfig exposes a single key:

liquibase {
  changelog = "db/changelog/db.changelog-master.xml"   // default
}

Point it at a formatted-SQL master to keep native SQL:

liquibase {
  changelog = "db/changelog/db.changelog-master.sql"
}

Two asymmetries against Flyway that matter:

• There is no liquibase.enabled key. LiquibaseJdbcDatabaseInterceptor.afterInit runs update() unconditionally. To stop in-app migration you must remove LiquibaseJdbcDatabaseModule from the @KoraApp interface — there is no config switch.
• No dialect artifact is needed. org.liquibase:liquibase-core 5.0.3 aggregates liquibase-standard, which carries the mainstream database implementations; the framework's own Liquibase test migrates a real PostgreSQL with liquibase-core alone.

Formatted-SQL changelogs need a header line and a --changeset per change; rollback is declared with --rollback:

--liquibase formatted sql

--changeset developer:1
CREATE TABLE users (
    id    BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE
);
--rollback DROP TABLE users;

Changeset directives, contexts/labels, includes and rollback patterns — references/liquibase-migration-reference.md.

5. Choosing between them

Plug in exactly one. Both interceptors attach to the same JdbcDataSource node and would both manage the same schema.

6. Out-of-process migrations (recommended for scaled services)

§1 established the mechanism: the interceptor runs during graph initialization, once per replica, on every rollout. Both tools serialize concurrent runs with a database lock (Flyway around flyway_schema_history, Liquibase via DATABASECHANGELOGLOCK), so replicas do not corrupt each other — but every pod still waits for that lock, a run that dies mid-migration can leave it held, and a bad migration takes down the whole rollout rather than one job. For anything beyond a single instance, run migrations once, before the app starts.

Local development — Flyway Gradle plugin. The canonical kora-java-crud example takes this route: it wires only JdbcDatabaseModule, with no database-flyway dependency at all, and migrates through the plugin.

buildscript {
    dependencies {
        // the plugin runs in the Gradle JVM, so the dialect goes on the buildscript classpath
        classpath "org.flywaydb:flyway-database-postgresql:13.3.0"
    }
}

plugins {
    id "org.flywaydb.flyway" version "13.3.0"
}

flyway {
    url       = "jdbc:postgresql://localhost:5432/mydb"
    user      = "postgres"
    password  = "postgres"
    locations = ["classpath:db/migration"]
    baselineOnMigrate = true
}

./gradlew flywayMigrate

Keep the plugin and its dialect artifact on the same version. (kora-java-crud currently pairs plugin 13.0.0 with dialect 12.10.0; treat that as example drift, not a pattern to copy.)

Production — Kubernetes Job run once before the rollout, with the app keeping flyway.enabled = false (Flyway) or no migration module at all (Liquibase):

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
spec:
  backoffLimit: 1
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: flyway
          image: flyway/flyway:13.3.0
          args: ["migrate"]
          env:
            - name: FLYWAY_URL
              valueFrom: { configMapKeyRef: { name: db-config, key: url } }

The Liquibase equivalent is liquibase/liquibase:5.0.3 with args: ["--changelog-file=db/changelog/db.changelog-master.xml", "update"], or the org.liquibase.gradle plugin (3.1.0) locally.

CI — run the same command as a pipeline step against the target database before deploying.

7. Common pitfalls

References & assets

Related skills

• kora-database-jdbc — JdbcDatabaseModule, the jdbc section, repositories (prerequisite)
• kora-config-hocon — how the flyway / liquibase sections are mapped
• kora-config-yaml — the YAML form of the same sections
• kora-testing-junit-java · kora-testing-junit-kotlin — @KoraAppTest + Testcontainers with migrations
• kora-project-dependencies — BOM, module coordinates, externally-versioned dependencies
• kora-di-runtime — GraphInterceptor and graph lifecycle

Source of truth

Version-aligned authorities for Kora 2.0. The published documentation site describes Kora 1.x (ru.tinkoff.kora) on every branch, including pages served under a /v2/ path — never resolve a 2.0 migration question from it.

• Framework source, tag 2.0.0.RC1: database-flyway · database-liquibase · database-jdbc
• Migrated guide apps, branch migration/2.0 (in-app Flyway): kora-java-guide-database-jdbc-advanced-app · kora-kotlin-guide-database-jdbc-advanced-app
• Migrated examples, branch migration/2.0: kora-java-crud (Gradle-plugin strategy) · kora-java-petclinic (in-app module)
• Third-party: Flyway 13 docs · Liquibase docs