gradle-jooq-plugin

The work on this software project is in no way associated with my employer nor with the role I'm having at my employer. Any requests for changes will be decided upon exclusively by myself based on my personal preferences. I maintain this project as much or as little as my spare time permits.

Overview

Gradle plugin that integrates jOOQ. For each jOOQ configuration declared in the build, the plugin adds a task to generate the jOOQ Java sources from a given database schema and includes the generated sources in the specified source set. Multiple configurations are supported. The code generation tasks fully participate in the Gradle uptodate checks. The plugin can be applied on both Java projects and Android projects.

You can find out more details about the actual jOOQ source code generation in the jOOQ documentation.

The plugin is hosted on the Gradle Plugin portal.

Build scan

Recent build scan: https://gradle.com/s/bkc4davu2dvu4

Find out more about build scans for Gradle and Maven at https://scans.gradle.com.

Applying the plugin

Apply the nu.studer.jooq plugin to your Gradle project.

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

Please note that due to non-backward compatible API changes in jOOQ between 3.10.x and 3.11.x, you must apply the following plugin version in your Gradle build:

jOOQ library <= 3.10.x: gradle-jooq plugin 2.0.11
jOOQ library >= 3.11.x: gradle-jooq plugin 3.0.0 or higher

Defining your database drivers

Depending on which database you are connecting to, you need to put the corresponding driver on the generator's classpath.

dependencies {
    jooqRuntime 'postgresql:postgresql:9.1-901.jdbc4'
}

Specifying the jOOQ version and edition

This plugin supports existing and future jOOQ versions. It also supports the different editions like open source, pro, and trial.

jooq {
  version = '3.13.1' // the default (can be omitted)
  edition = 'OSS'    // the default (can be omitted), other allowed values are PRO, PRO_JAVA_8, PRO_JAVA_6, TRIAL, TRIAL_JAVA_8, TRIAL_JAVA_6
}

The plugin ensures that all your dependencies use the version and edition specified in the jooq configuration. So when you declare a compile dependency on jOOQ, you can omit the version:

dependencies {
  implementation 'org.jooq:jooq'
}

Tasks

For each jOOQ configuration declared in the build, the plugin adds a new generate[ConfigurationName]JooqSchemaSource task to your project. Each task generates the jOOQ Java sources from the configured database schema and includes these sources in the specified source set. For example, a jOOQ configuration named sample will cause the plugin to add a new code generation task generateSampleJooqSchemaSource to the project.

gradle generateSampleJooqSchemaSource

By default, the code generation tasks are automatically configured as dependencies of the corresponding source compilation tasks provided by the JavaBasePlugin plugin. Hence, running a build that eventually needs to compile sources will first trigger the required jOOQ code generation tasks. This auto-triggering of the code generation when compiling the containing source set can be turned off by setting generateSchemaSourceOnCompilation to false.

You can delete all files in the folder that you configure as the output directory of the code generation task by running the Gradle task rule cleanGenerate[ConfigurationName]JooqSchemaSource. Note that this task rule will delete all files in the configured output folder, regardless of whether the files were generated by the jOOQ plugin or not.

gradle cleanGenerateSampleJooqSchemaSource

To see the log output of the jOOQ code generation tool, run the Gradle build with log level info:

gradle build -i

Configuration

The example below shows a jOOQ configuration that creates the jOOQ Java sources from a PostgreSQL database schema and includes them in the main source set.

By default, the generated sources are written to build/generated-src/jooq/<configurationName>. The output directory can be configured by explicitly setting the directory attribute of the target configuration.

See the jOOQ XSD for the full set of configuration options.

jooq {
  version = '3.13.1'
  edition = 'OSS'
  generateSchemaSourceOnCompilation = true
  sample(sourceSets.main) {
    jdbc {
      driver = 'org.postgresql.Driver'
      url = 'jdbc:postgresql://localhost:5432/sample'
      user = 'some_user'
      password = 'secret'
      properties {
        property {
          key = 'ssl'
          value = 'true'
        }
      }
    }
    generator {
      name = 'org.jooq.codegen.DefaultGenerator'
      strategy {
        name = 'org.jooq.codegen.DefaultGeneratorStrategy'
        // ...
      }
      database {
        name = 'org.jooq.meta.postgres.PostgresDatabase'
        inputSchema = 'public'
        forcedTypes {
          forcedType {
            name = 'varchar'
            expression = '.*'
            types = 'JSONB?'
          }
          forcedType {
            name = 'varchar'
            expression = '.*'
            types = 'INET'
          }
        }
        // ...
      }
      generate {
        relations = true
        deprecated = false
        records = true
        immutablePojos = true
        fluentSetters = true
        // ...
      }
      target {
        packageName = 'nu.studer.sample'
        // directory = ...
      }
    }
  }
}

Configuration pitfalls

Configuring a sequence of elements

Resemblance of the jOOQ configuration DSL with the Groovy language is coincidental. Complex types that include sequences like ForcedTypes must be defined in the DSL's nesting style:

forcedTypes {
  forcedType {
    name = 'varchar'
    expression = '.*'
    types = 'JSONB?'
  }
  forcedType {
    name = 'varchar'
    expression = '.*'
    types = 'INET'
  }
}

The Groovy list style is not supported:

forcedTypes = [
  {
    name = 'varchar'
    expression = '.*'
    types = 'JSONB?'
  },
  {
    name = 'varchar'
    expression = '.*'
    types = 'INET'
  }
]

Defining matchers

When using matchers, the name element must be set to null explicitly:

strategy {
  name = null
  matchers {
    tables {
      table {
        pojoClass {
          transform = 'PASCAL'
          expression = '\$0_POJO'
        }
      }
    }
  }
}

Background: the plugin consumes JAXB classes generated from the jOOQ XSD. The name on the Strategy element has a default value and that's an issue since is part of an XSD choice element, i.e. only one element can be present. This is the only choice element in the whole XSD, so this workaround only needs to be applied here.

Defining the jOOQ version when the Spring boot plugin is applied

When applying the spring-boot-gradle-plugin, it is not sufficient to declared the jOOQ version that you want to pull in via jooq.version = '3.13.1' since the dependency management rules of the spring-boot-gradle-plugin take precedence. You also have to set ext['jooq.version'] = '3.13.1' to pull in your requested version of jOOQ.

Generating sources into shared folders, e.g. src/main/java

My recommendation is to generate the jOOQ sources into a distinct folder, e.g. src/generated/jooq or build/generated-src/jooq (default). This avoids overlapping outputs, and it also keeps the door open to let Gradle cache the generated sources which can be a significant build performance gain. The rationale is explained very well in the Build Cache User Guide.

Samples

Passing JVM args to the jOOQ code generation process: here.
Removing the implicit task dependency between the compile task and the jOOQ source generation task: here.
Using a custom generator strategy defined in the same Gradle project: here.
Running on JDK 9 and higher with all JAXB dependencies already added by the plugin: here.
Running on JDK 11 and higher with manual addition of the annotation API: here.
Configuring the jOOQ code generation via Kotlin DSL: here.
Configuring the jOOQ code generation via Groovy DSL in a Kotlin DSL build: here.

Changelog

4.2 - Add new jOOQ editions for Java 8 and Java 6. Upgrade to jOOQ 3.13.1.
4.1 - Global flag to turn off auto-generation of jOOQ schema source when compiling the containing source set
4.0 - Make Gradle 5.0 the minimum compatible version. Upgrade to jOOQ 3.12.3.
3.0.3 - Explicitly add JAXB dependencies to run on JDK 9 and higher out-of-the-box. Upgrade to jOOQ 3.11.9.
3.0.2 - Bug fix when running on JDK 9+
3.0.1 - Improve Gradle build cache effectiveness of the jOOQ task
3.0.0 - Upgrade to jOOQ 3.11.2 (jOOQ 3.11.x breaks compatibility with jOOQ 3.10.x)
2.0.11 - Upgrade to jOOQ 3.10.4
2.0.10 - Removal of wiring between clean task and deleting generated jOOQ sources
2.0.9 - Make jOOQ 3.10.1 the default applied version
2.0.8 - Upgrade to jOOQ 3.10.1
2.0.7 - Upgrade to jOOQ 3.9.5
2.0.6 - Upgrade to jOOQ 3.9.3
2.0.5 - Make the jOOQ task parallelizable
2.0.4 - Upgrade to jOOQ 3.9.1 and better configuration error messages
2.0.3 - Upgrade to jOOQ 3.9.0
2.0.2 - Configuration of call-backs for code generation java execution process
2.0.1 - Bug fixes
2.0.0 - Make jOOQ version used for code generation independent from jOOQ version used by gradle-jooq plugin
1.0.6 - Upgrade to jOOQ 3.6.2

Acknowledgements

Sineaggi (pr)
martintreurnicht (pr)
anuraaga (pr)
ldaley (pr)
masc3d (pr)
mark-vieira (pr)
felipefzdz (commits)
oehme (pr)
jamespedwards42 (idea)
dubacher (patch)
lukaseder (patch)

License

This plugin is available under the Apache License, Version 2.0.

benmccann / gradle-jooq-plugin Goto Github PK