Generating jOOQ code from Flyway migrations, without a database

Behzod Halil·August 27, 2026·7 min read

jOOQ generates its code from a schema, which means something has to be holding a schema at build time. The usual answer is a database, and a database is the one thing our CI does not have.

StockPlus runs a Spring Boot backend where every query is written in the jOOQ DSL, so nothing on the server compiles until the generator has produced its classes. The GitHub Actions workflow has no services: block, no Docker, and no Postgres. This is how the schema gets there anyway, which property in the config is the one to read twice, and the single migration mistake that no build configuration can catch.

Where we stood

Three facts, and the shape of the problem falls out of them.

• Flyway owns the schema. It is described by 54 migration files, latest version V56, applied in order at startup. The description already exists, in the repo, in SQL.
• Code generation is not an occasional chore. The Gradle config sets generateSchemaSourceOnCompilation.set(true), so it runs before every compile, on a laptop and in CI alike. Anything it depends on is on the critical path of every build.
• CI has two jobs, :server:test and :server:bootJar, on a plain ubuntu-latest runner with a JDK and a Gradle cache. No service container, no database.

So the schema is right there in a directory, and the question is only whether the code generator can be made to read it. What we ended up with is one directory read by two different things at two different times:

Four ways to hand jOOQ a schema, and why three of them lose

Point the generator at a live database. This is what most jOOQ setups do and it is the path of least resistance. It also makes the build depend on a machine. Whoever ran migrations last decides what your generated API looks like; a colleague sitting on an older branch generates a different one; CI needs a service container and a wait-for-healthy step. Worst of all, drift is silent in the direction that hurts: apply a migration by hand, never commit it, and codegen cheerfully generates the column while the repo has no record of it.

Start a container, migrate, generate, tear it down. Testcontainers does this well and it is the right answer for a lot of projects, because a real Postgres accepts anything Postgres accepts. It needs a Docker daemon wherever the build runs, which our runner does not have, and it puts a container start on the path of every compile rather than once per CI run.

Declare the schema a second time, as entities. The JPA answer, and it is ruled out here for a reason that has nothing to do with taste: two descriptions of one schema drift, and the one that drifts is never the one you are looking at.

The fourth option is the one that fits. jooq-meta-extensions ships DDLDatabase, which runs DDL through jOOQ’s own SQL parser and builds an in-memory schema out of the result. No server, no container, and no second declaration — it reads the same files Flyway applies. jOOQ documents it under code generation from DDL files, and the Gradle side is the gradle-jooq-plugin.

The configuration is about ten lines

jooqGenerator("org.jooq:jooq-meta-extensions:${libs.versions.jooq.get()}")

// ...

database.apply {
    name = "org.jooq.meta.extensions.ddl.DDLDatabase"
    properties = listOf(
        Property().withKey("scripts")
            .withValue("src/main/resources/db/migration/*.sql"),
        Property().withKey("sort").withValue("flyway"),
        Property().withKey("defaultNameCase").withValue("lower"),
    )
}

scripts is a glob over the Flyway directory. Note what is not there: a copy, an export, a dump. It is the same directory Flyway reads at runtime, so there is no second artifact to keep in sync and no way for the generated code to describe a schema the application will not actually get.

sort is the one to read twice. It decides the order the scripts are applied in before the schema is assembled, and the default is lexical. Lexically, V10 sorts before V2. Apply DDL in that order and a migration that alters a table runs before the migration that creates it. The failure itself is loud; the cause is not, because everything worked for nine migrations and the tenth is where it starts. Setting it to flyway parses the version out of the filename and orders the way Flyway does.

defaultNameCase matters because Postgres folds unquoted identifiers to lower case. Leave it and the parsed schema keeps whatever case the DDL was typed in, so the generated constants stop matching the names the running database will answer to. All three are documented among the code generation configuration options, and the version scheme sortis parsing is Flyway’s own, from the Flyway documentation.

What it costs

This is a parser, not a database, and the difference shows up in three places.

It constrains what you may write in a migration. Every statement has to be something jOOQ’s parser understands. Across all 54 migration files here there is no CREATE EXTENSION, no DO $$ ... $$ block, and no function or trigger. That stopped being a coincidence the moment the build depended on it: reach for a Postgres-only construct now and the thing that tells you no is the code generator, not the database.

It generates what Flyway would produce, not what production has. If someone altered a table by hand in production, this setup cannot see it, because it never looks at production. A generator pointed at a live database can. That is the one honest argument for the option we rejected, and it is worth saying plainly rather than discovering later.

There is no data, and therefore no statistics. Anything in a generator that wants to inspect rows rather than structure has nothing to work with.

What it bought

The 22.6 seconds is a cold, deliberately pessimistic number: no daemon and every task re-run. The 923 ms is what generation itself costs once Gradle has started, and it is the figure that matters, because generateSchemaSourceOnCompilation means you pay it often.

The one mistake this cannot catch

This is exactly as trustworthy as the migration directory itself. Nothing in the config above has an opinion about whether that directory makes sense, and there is one way for it to stop making sense that no amount of care prevents.

Two branches each add a V53. Both are individually correct, both pass review, both pass their own tests. Flyway refuses to start when two migrations share a version, and it throws during validate, before Spring’s context is up, so the application does not boot at all. The database is untouched, nothing is applied, and the deployment is dead.

It happened here on 25 August 2026: V53__institution_curation_identity.sql and V53__add_briefing_push_prefs.sql merged minutes apart.

The reason this needs more than discipline is that the collision is invisible in the change that creates it. Each diff is clean on its own. The conflict comes into existence at the moment the second branch merges, which is precisely when nobody is reading. Checking the highest version on main before merging does not help either: main can gain a migration between the check and the merge.

Treat for the curious

The fix is a test, not a process, because it has to look at the whole tree rather than at a diff.

private val migrationDir = File("src/main/resources/db/migration")

/** `V53__add_briefing_push_prefs.sql` -> `53`. */
private fun versionOf(file: File): String? =
    Regex("""^V(\d+(?:[._]\d+)*)__""").find(file.name)?.groupValues?.get(1)

@Test
fun `GIVEN the migration directory WHEN versions are grouped THEN none repeats`() {
    // GIVEN
    val migrations = migrationDir.listFiles { f -> f.name.endsWith(".sql") }.orEmpty()

    // WHEN
    val duplicates = migrations
        .mapNotNull { file -> versionOf(file)?.let { it to file.name } }
        .groupBy({ it.first }, { it.second })
        .filterValues { it.size > 1 }

    // THEN
    assertTrue(duplicates.isEmpty(), /* ... names the colliding files ... */)
}

The name carries the whole specification and the body markers stay bare, which is this repo’s convention rather than a flourish. A failing build prints that name, so the report says what broke without anyone opening the file.

It runs against whatever is actually on the branch, so a merge or a rebase that introduces the collision fails the build rather than the deploy. That is the entire trick: move the check from the diff, where the problem is invisible, to the directory, where it is obvious.

A second test in the same class catches the quieter sibling. A filename typo like V53_add_thing.sql, with one underscore instead of two, is silently ignored by Flyway rather than rejected. The migration never runs, the column it adds never exists, and the first thing you learn about it is a query failing in production.

What generalises

• When a build step needs a schema, prefer the description you already version over a server you have to run. The migrations were always the source of truth; pointing the generator at them removes a moving part rather than adding one.
• Config properties that look cosmetic usually encode an ordering or an identifier assumption. Those are the ones that hold for every input you have tried and then stop.
• A mistake that is invisible in its own diff cannot be caught by review, however careful. It needs something that looks at the whole tree, and that something is usually cheaper to write than the incident it prevents.

None of this is really about jOOQ. It is about which artifact you let a build depend on, and preferring the one that is already versioned.

The client half of this app produced the same lesson in a different register: moving its push pipeline to OneSignal turned up a send that returned HTTP 200 while delivering nothing to anybody. A duplicate migration version and a successful-looking failed push are the same species of bug: the system had every chance to say so and did not.

The server described here backs StockPlus, an app for following congressional and insider filings, 13F holdings and price alerts on iOS and Android. The interesting parts of building it are mostly the parts you cannot see from a store listing, which is what this blog is for.