gradle-jooq-plugin: jOOQ code generation inside a Gradle build

Generating jOOQ classes from a live schema during the build

The problem this plugin solves is narrow and real. jOOQ generates a Java type-safe DSL from the structure of a database, and that structure lives in the database rather than in the source tree. Teams end up with two options: commit the generated code and live with the diff, or run the generator as a separate step before every build and hope everyone remembers. The plugin takes the second option and puts it inside Gradle. The README states that for each named jOOQ configuration declared in the build, the plugin adds a task to generate the jOOQ sources from the specified database schema and includes the generated Java sources in the matching source set, if existing. The people it serves are Java and Android developers on Gradle, including teams writing in the Kotlin DSL.

One JooqGenerate task per named configuration

The mechanism is a task per configuration rather than a single global task. Each named jOOQ configuration in the build gets its own JooqGenerate task, and the plugin does more than create the task: it wires task dependencies so the generated sources exist before the Java compile task of the name-matching source set compiles them, if that source set exists. It also adds the generated Java sources to that source set. One option is provided to suppress the automatic wiring between the compile task and the generation task, which matters when a project needs to control the ordering itself. The consequences of this design are visible in the example directory of the repository, which contains separate examples for configuring a custom generator strategy, configuring different jOOQ sources for the same target source set, configuring generation tool execution, and configuring task dependencies, among others. Each of those directories corresponds to a real decision a build author has to make.

Applying nu.studer.jooq in either DSL

The plugin is published on the Gradle Plugin Portal under the id nu.studer.jooq, and applying it is a two-line change to the plugins block. The README gives the Groovy DSL form:

plugins {
    id 'nu.studer.jooq' version '10.2.1'
}

and the equivalent Kotlin DSL form, with the same version string:

plugins {
    id("nu.studer.jooq") version "10.2.1"
}

Support for both DSLs is listed as first-class, and the compatibility table marks Kotlin DSL support as present for every plugin version from 4.0 onwards, with 4.0 being the exception that has no Kotlin DSL support. Nothing else is required to start: the plugin id, the version, and then the configuration of the generation itself.

The jooqGenerator configuration and the two dependencies it adds

The plugin contributes two dependency changes to the build, and both matter for how the build resolves. First, the jOOQ code generation tool itself is added to a new configuration named jooqGenerate, in the form of the edition-specific jooq-codegen artifact for the chosen version. Second, the edition-specific jooq artifact for the same version is added to the name-matching implementation configuration, so the generated sources compile. Separately, the database driver that the generation tool will introspects has to be on the classpath, and that is what the jooqGenerator configuration is for. The README's example adds a PostgreSQL driver:

dependencies {
    jooqGenerator 'org.postgresql:postgresql:42.7.8'
}

and the same thing in the Kotlin DSL:

dependencies {
    jooqGenerator("org.postgresql:postgresql:42.7.8")
}

Additional dependencies needed to run the generation tool can be added to that same configuration. The split between a code generation dependency and a runtime dependency is the part worth remembering, because the version of jOOQ used to generate the code and the version used to compile it have to line up.

Configuration cache, isolated projects and the version matrix

The plugin is explicit about which modern Gradle features it takes part in, and the compatibility table is the fastest way to understand the trade-off between versions. For plugin version 10.0 and later, the compatible Gradle versions are 8.6 and later, the minimum JDK is 21 and the minimum jOOQ is 3.16. For 9.0 and later, Gradle 8.0 and later with JDK 17 and jOOQ 3.16 or later. Older lines step down: 8.2.2 and 8.0 require Gradle 7.0, 7.0 and 6.0 and 5.0 accept Gradle 6.1 and 7.0 with JDK 11, and 4.0 accepts Gradle 5.0 through 7.0 with JDK 8 and jOOQ 3.15 or lower. Configuration Cache support is listed as yes from 5.0 onwards, and Isolated Projects support appears from 8.2.2, and only for Gradle 9.7 or later.

Incremental builds and output caching need declared inputs

There is a catch in the feature list that is easy to miss on first read. JooqGenerate task instances participate in task configuration avoidance, in incremental builds, in task output caching and in toolchains, but the README adds a condition to two of those: they participate if the task gets explicitly marked as all inputs being declared. Configuration avoidance and toolchain participation carry no such condition, while configuration cache and isolated projects compatibility are listed as plugin level statements. The practical effect is that a build wanting incremental generation and build cache hits has to declare its inputs properly, and the repository carries a dedicated example directory for exactly that, named for configuring incremental build and build caching participation. Another example shows how to set JVM arguments for the generation tool, which matters because introspection against a remote database can need more heap than the default.

The jOOQ project's own Gradle plugin, and what this one adds

The README names an alternative without disparaging it: the jOOQ project provides its own Gradle plugin that you might consider as an alternative. The difference in approach is visible in the documentation. This plugin's own documentation concentrates on Gradle integration concerns: named configurations, source set matching, task wiring, the dependency split between jooqGenerate and implementation, and participation in the configuration cache and isolated projects. The plugin also states that the details of the actual jOOQ source code generation live in the jOOQ documentation, and it points to the jOOQ code generation manual rather than duplicating it. So the choice is between a plugin that owns the Gradle wiring around generation and one that comes from the tool vendor itself. On maintenance, the plugin is under Apache-2.0, the last push was on 2026-10-01, and the recent tags are v10.2.1 on 2026-03-18, v10.2 on 2025-12-27 and v10.1.1 on 2025-08-02, the first of those marking the plugin as Configuration Cache compatible and the second a Gradle and jOOQ upgrade. The README also states plainly that the work is done in the author's spare time and that change requests are decided on personal preference, which is a factor for a build-critical plugin.

Editorial conclusion

gradle-jooq-plugin fits a Java or Android project that already uses Gradle and wants jOOQ generation to run inside the same build, with the generated sources compiled by the normal compile task. It does not fit a project that wants to avoid an extra plugin in the build file, and the README itself points at the jOOQ project's own Gradle plugin as an alternative worth considering. Verify first which plugin version matches your Gradle and JDK, since 10.0+ requires Gradle 8.6 and JDK 21 while 9.0+ requires Gradle 8.0 and JDK 17, then check the examples in the example directory for the exact pattern your build needs.

Frequently asked questions

Official sources

1. etiennestuder/gradle-jooq-plugin on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases