DEV Community: Behzod Halil

jOOQ codegen from Flyway migrations, with no database

Behzod Halil — Sat, 29 Aug 2026 15:18:10 +0000

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:

One directory, two readers. Neither of them needs the other to have run.

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"),
    )
}

Kotlin, server/build.gradle.kts

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 sort is parsing is Flyway’s own, from the Flyway documentation.

A config property that looks cosmetic in a code generator is usually encoding an assumption about ordering or identifiers. Those are the two places where a build can be correct on every input you have tried so far.

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

Measure	Result
Database at build time	none
Docker in CI	none
Generation, jOOQ's own timer	923 ms
Full `generateJooq`, `--rerun-tasks --no-daemon`	22.6 s wall clock
Generated output	164 files, 53 tables
Descriptions of the schema in the repo	one

Measured 27 August 2026, Apple M4, Gradle with no daemon, no Postgres installed and the Docker daemon stopped.

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 ... */)
}

Kotlin, FlywayMigrationVersionsTest.kt

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.

If you copy this, decide what you want it to do about repeatable migrations. Our version regex returns null for an R__ file and the second test asserts that nothing is null, so adding a repeatable migration would fail the build with a message about an unparseable filename. There are none in this repo today, which is the only reason the two tests agree.

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.

Shipping OneSignal push in a Kotlin Multiplatform app

Behzod Halil — Fri, 28 Aug 2026 13:57:38 +0000

Originally published on getstockplus.app.

Most of a push-notification implementation has nothing to do with the product. Token tables, refresh callbacks, stale-token pruning, a separate iOS pipeline: none of it is the feature, and all of it needs maintaining.

StockPlus is a Kotlin Multiplatform app whose core product is price alerts, delivered as push notifications. This is how we moved it from direct Firebase Cloud Messaging to OneSignal: what actually changed architecturally, and the four silent failures that had to be hunted down along the way.

Addressing users, not devices

Direct FCM builds a message around a registration token. One token, one device. That sounds simple, but it quietly generates a lot of server-side work: a table of tokens per user, a refresh callback because tokens rotate, pruning on UNREGISTERED because they go stale, a hand-written fan-out loop because a phone and a tablet are two rows, and an entirely separate iOS pipeline with separate credentials.

OneSignal inverts the unit of addressing. The client declares an identity:

OneSignal.login(userId)

The server then addresses that identity instead of a device:

mapOf(
    "app_id" to appId,
    "target_channel" to "push",
    "include_aliases" to mapOf("external_id" to listOf(userId)),
    "headings" to mapOf("en" to title),
    "contents" to mapOf("en" to body),
    "data" to data,
)

One HTTP call reaches every device where that user is logged in, on both platforms, and the OneSignal path stores no device tokens of its own. (The legacy users.fcm_token column is still there, still feeding the old channel described below.) The real change is the unit of addressing, not the vendor. The migration removed more lines than it added, which is usually a good sign: deleted code has no bugs and needs no tests.

No flag day

The pipeline was already live and price alerts are the product, so a big-bang cutover was out. The new channel went in beside the old one, selected purely by configuration:

val isEnabled: Boolean
    get() = appId.isNotBlank() && restApiKey.isNotBlank()

external:
  onesignal:
    app-id: ${ONESIGNAL_APP_ID:}       # unset => legacy FCM path
    rest-api-key: ${ONESIGNAL_REST_API_KEY:}

Deploying the code is not the cutover: the binary behaves exactly as before until the credentials are set. Rollback is an environment variable rather than a revert. Local dev and CI have no credentials, so they transparently use the legacy path and nothing ever accidentally sends from a laptop. Note which way the default points: doing nothing gets you the old, proven behaviour.

The legacy path has to stay fully functional: retries, backoff, stale-token pruning, all of it. A fallback that has quietly rotted is not a fallback.

Durable first, push second

This is the design decision worth defending hardest, and it applies whichever vendor you pick: a push notification is not the notification. It is an announcement that a notification exists.

Every send path persists a durable inbox row first, then attempts the push:

fun sendAlertTriggered(
    fcmToken: String?,
    ticker: String,
    alertType: AlertType,
    price: BigDecimal?,
    userId: UUID,
) {
    val (title, body) = buildAlertMessage(ticker, alertType, price)
    // Inbox is the source of truth; the push below is best-effort.
    notificationRepository.save(userId, title, body, alertType.name, ticker)

    deliverPush(fcmToken, userId, title, body, mapOf(/* ... */))
}

Push delivery is genuinely unreliable, and not because the vendors are bad at it: denied permissions, offline devices, OS throttling, rotated tokens, guest users. On iOS, best-effort delivery is the explicit platform contract. Ordering it durable-first turns each of those failures from lost product data into a missed buzz: the alert is sitting in the inbox when the user next opens the app. It also lets the whole push layer be best-effort all the way down: no retries blocking a request, no transaction spanning an HTTP call, no error a user can ever see.

One declaration, opposite directions

Shared code depends on an expect class. Both platforms satisfy the same declaration, but they satisfy it in opposite directions, so it has to stay narrow enough that neither implementation needs to widen it:

expect class PushIdentityBinder() {
    fun login(userId: String)
    fun logout()
}

Android is the easy one: the OneSignal SDK is a Gradle dependency, so the implementation calls it directly. It never throws (any vendor surprise degrades to "no push", never to "sign-in crashed"):

actual class PushIdentityBinder actual constructor() {
    actual fun login(userId: String) {
        runCatching { OneSignal.login(userId) }
    }

    actual fun logout() {
        runCatching { OneSignal.logout() }
    }
}

iOS is where it gets interesting. The OneSignal iOS SDK is a Swift package, and Kotlin cannot see it: Swift sees Kotlin through the generated framework, but not the reverse. So on iOS the control flow is inverted: Kotlin holds the closures, and Swift fills them in at startup.

object IosPushIdentityBridge {
    var onLogin: ((String) -> Unit)? = null
    var onLogout: (() -> Unit)? = null
}

One wrinkle costs a confusing hour the first time. The module holding that object is an implementation dependency of the iOS framework rather than an exported one, so its symbols never appear in the framework header and Swift cannot see the bridge at all. The fix is a thin re-export in the module that is exported:

fun setPushIdentityHandlers(
    onLogin: (String) -> Unit,
    onLogout: () -> Unit,
) {
    IosPushIdentityBridge.onLogin = onLogin
    IosPushIdentityBridge.onLogout = onLogout
}

PushBridgeKt.setPushIdentityHandlers(
    onLogin: { userId in OneSignal.login(userId) },
    onLogout: { OneSignal.logout() }
)

That call has to run before the root component spins up. A cold start with a saved session binds identity immediately, and getting the order wrong silently no-ops on exactly the launch that matters most: a returning, logged-in user.

Desktop binds a no-op. Three platforms, three strategies (direct call, inverted callback, deliberate nothing) behind one interface with zero conditionals in shared code.

Nothing threw, nothing was red

Push is a pipeline of best-effort steps, which means its default failure mode is silence. Four silent failures turned up.

The successful failure. OneSignal returns HTTP 200 with a populated errors field when no subscribed device matches the external id, so a naive response.isSuccessful check reports permanent success whilst delivering nothing, forever. The body has to be parsed.

The obvious parse is wrong too, and we shipped it before fixing it. Treating any non-empty errors array as failure misreads a broadcast: a chunk where one id out of five hundred is unknown lists that id under errors and still delivers to the other four hundred and ninety-nine. recipients is the field that separates partial from total failure, so errors are logged for visibility and only a zero recipient count is treated as a failure:

val json = objectMapper.readTree(responseBody)
val errors = json.path("errors")
val hasErrors = !errors.isMissingNode && errors.size() > 0
if (hasErrors) log.info("OneSignal reported errors for {}: {}", label, errors)

// An absent "recipients" falls back to the errors-only test, so a response
// shape we do not recognise is still a failure rather than silently a success.
val recipients = json.path("recipients")
val deliveredNothing =
    if (recipients.isInt) recipients.asInt() == 0 else hasErrors

Transport success is not application success.

The misconfiguration in camouflage. The legacy path had two skip conditions with byte-identical behaviour: Firebase never initialised (someone forgot an env var), and no token on file (completely normal for guests). Both silently sent nothing. Now the first logs a warn naming the exact variable to check, and the second logs debug. When a broken configuration and a normal condition produce the same behaviour, they must not produce the same log.

The early return that only breaks one platform. This one nearly shipped:

suspend operator fun invoke(token: String? = null): AppResult<Unit> {
    // Identity binding FIRST: it needs only the userId. On iOS the FCM token
    // is always null; OneSignal is the only push channel there.
    sessionManager.currentUserId()?.let(pushIdentityBinder::login)

    val resolvedToken = token ?: pushTokenProvider.getToken()
    if (resolvedToken.isNullOrBlank()) {
        return AppResult.Error("No push token available", "NO_PUSH_TOKEN")
    }
    return pushTokenRepository.registerToken(resolvedToken, pushTokenProvider.platform)
}

The obvious ordering (fetch the token, bail if null, then do the rest) gates identity binding behind a token that is always null on iOS. Android works perfectly; iOS never calls login(), never matches a send, and reports no error anywhere. In shared multiplatform code an early return guards everything after it on every platform, so it is worth asking whether the guard's precondition is even meaningful on all of them.

The transitive dependency. The OneSignal dashboard showed zero Android recipients whilst iOS delivered fine. The SDK's verbose logging showed FIREBASE_FCM_INIT_ERROR: the device had never subscribed at all. The dependency tree explained why: OneSignal 5.9.8 supports firebase-messaging [23.0.8, 24.0.99], but an unrelated Firestore feature pulled in the Firebase BOM, which forced 24.1.1. Gradle's conflict resolution picks the highest version, not one satisfying every constraint, so the build stayed green and the registrar died on real devices.

configurations.configureEach {
    resolutionStrategy.force("com.google.firebase:firebase-messaging:24.0.0")
}

That block is declared in three modules (the push module itself, the shared entrypoint, and the Android application module) and the duplication is load-bearing: resolutionStrategy only governs the declaring module, and it is the application module that resolves the classpath actually shipping in the APK. Your version catalog records what you asked for; ./gradlew :entrypoint:android:dependencies records what you got.

Two traps

Do not declare your own MESSAGING_EVENT service. It wins over the one OneSignal merges in from its AAR, and data-only pushes get silently dropped. Our manifest carries a permanent comment saying so, because there is no lint check for code that must not exist.
Call OneSignal.logout() before clearing the session: it needs the outgoing access token. Reverse the order and a signed-out phone keeps receiving the previous account's price alerts. That is not a missing-notification bug, that is a data leak, one line of ordering away.

What actually mattered

The SDK calls really are two lines, and the two lines were never the work. What mattered was picking the addressing model before the vendor, making push best-effort by making something else durable first, migrating behind configuration with the safe path as the default, and hunting silent failures deliberately: verbose vendor logging on day one, parsing bodies rather than trusting status codes, and giving misconfiguration a louder log than normal operation.

Very little of this is OneSignal-specific. The durable-first contract, the config-flag migration, and the control-flow inversion apply to any platform SDK your shared Kotlin code cannot see.

The same habit turns up on the server side of this app, where jOOQ generates its code straight from the Flyway migrations. Different stack, same question: which artifact are you willing to let the build depend on, and will it tell you when it is wrong?

Written by Behzod Halil. This is the push pipeline behind StockPlus, the Kotlin Multiplatform app it was built for. The original of this post lives on getstockplus.app.