LiquibaseDatabase: Code generation from Liquibase XML, YAML, JSON files
Applies to ✅ Open Source Edition ✅ Express Edition ✅ Professional Edition ✅ Enterprise Edition
If you are using Liquibase, you will have defined your database as a set of Liquibase change sets, in XML, YAML, or JSON. That database definition is complete and self contained, and can easily be used as a source of meta information by the jOOQ code generator.
For example, the following database.xml script could be used (please refer to the liquibase documentation for YAML or JSON formats):
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">
<changeSet author="authorName" id="changelog-1.0">
<createTable tableName="MY_TABLE">
<column name="MY_COLUMN" type="TEXT">
<constraints nullable="true" primaryKey="false" unique="false" />
</column>
</createTable>
</changeSet>
</databaseChangeLog>
In order to use the above as a source of jOOQ's code generator, you will simply need to set up your code generation configuration as follows:
<configuration>
<generator>
<database>
<name>org.jooq.meta.extensions.liquibase.LiquibaseDatabase</name>
<properties>
<!-- Specify the classpath location of your XML, YAML, or JSON script. -->
<property>
<key>scripts</key>
<value>/database.xml</value>
</property>
<!-- Whether you want to include liquibase tables in generated output
- false (default)
- true: includes DATABASECHANGELOG and DATABASECHANGELOGLOCK tables -->
<property>
<key>includeLiquibaseTables</key>
<value>false</value>
</property>
<!-- Properties prefixed "database." will be passed on to the liquibase.database.Database class
if a matching setter is found -->
<property>
<key>database.liquibaseSchemaName</key>
<value>lb</value>
</property>
<!-- The property "changeLogParameters.contexts" will be passed on to the
liquibase.database.Database.update() call (jOOQ 3.13.2+).
See https://www.liquibase.org/documentation/contexts.html -->
<property>
<key>changeLogParameters.contexts</key>
<value>!test</value>
</property>
</properties>
</database>
</generator>
</configuration>
See the configuration XSD, standalone code generation, and maven code generation for more details.
new org.jooq.meta.jaxb.Configuration()
.withGenerator(new Generator()
.withDatabase(new Database()
.withName("org.jooq.meta.extensions.liquibase.LiquibaseDatabase")
.withProperties(
// Specify the classpath location of your XML, YAML, or JSON script.
new Property()
.withKey("scripts")
.withValue("/database.xml"),
// Whether you want to include liquibase tables in generated output
//
// - false (default)
// - true: includes DATABASECHANGELOG and DATABASECHANGELOGLOCK tables
new Property()
.withKey("includeLiquibaseTables")
.withValue(false),
// Properties prefixed "database." will be passed on to the liquibase.database.Database class
// if a matching setter is found
new Property()
.withKey("database.liquibaseSchemaName")
.withValue("lb"),
// The property "changeLogParameters.contexts" will be passed on to the
// liquibase.database.Database.update() call (jOOQ 3.13.2+).
// See https://www.liquibase.org/documentation/contexts.html
new Property()
.withKey("changeLogParameters.contexts")
.withValue("!test")
)
)
)
See the configuration XSD and programmatic code generation for more details.
// The jOOQ-codegen-gradle plugin has been introduced in version 3.19 only.
// The jOOQ-codegen-gradle plugin has been introduced in version 3.19 only.
generationTool {
generator {
database {
name = "org.jooq.meta.extensions.liquibase.LiquibaseDatabase"
properties {
// Specify the classpath location of your XML, YAML, or JSON script.
property {
key = "scripts"
value = "/database.xml"
}
// Whether you want to include liquibase tables in generated output
//
// - false (default)
// - true: includes DATABASECHANGELOG and DATABASECHANGELOGLOCK tables
property {
key = "includeLiquibaseTables"
value = false
}
// Properties prefixed "database." will be passed on to the liquibase.database.Database class
// if a matching setter is found
property {
key = "database.liquibaseSchemaName"
value = "lb"
}
// The property "changeLogParameters.contexts" will be passed on to the
// liquibase.database.Database.update() call (jOOQ 3.13.2+).
// See https://www.liquibase.org/documentation/contexts.html
property {
key = "changeLogParameters.contexts"
value = "!test"
}
}
}
}
}
See the configuration XSD and gradle code generation for more details.
If you prefer not to work with the Liquibase ClassLoaderResourceAccessor and want to use the FileSystemResourceAccessor instead, you will need to provide a rootPath, starting from jOOQ 3.16, which depends on Liquibase 4 (or later).
<configuration>
<generator>
<database>
<name>org.jooq.meta.extensions.liquibase.LiquibaseDatabase</name>
<properties>
<!-- Specify the root path, e.g. a path in your Maven directory layout -->
<property>
<key>rootPath</key>
<value>${basedir}/src/main/resources</value>
</property>
<!-- Specify the relative path location of your XML, YAML, or JSON script. -->
<property>
<key>scripts</key>
<value>database.xml</value>
</property>
</properties>
</database>
</generator>
</configuration>
See the configuration XSD, standalone code generation, and maven code generation for more details.
new org.jooq.meta.jaxb.Configuration()
.withGenerator(new Generator()
.withDatabase(new Database()
.withName("org.jooq.meta.extensions.liquibase.LiquibaseDatabase")
.withProperties(
// Specify the root path, e.g. a path in your Maven directory layout
new Property()
.withKey("rootPath")
.withValue("${basedir}/src/main/resources"),
// Specify the relative path location of your XML, YAML, or JSON script.
new Property()
.withKey("scripts")
.withValue("database.xml")
)
)
)
See the configuration XSD and programmatic code generation for more details.
// The jOOQ-codegen-gradle plugin has been introduced in version 3.19 only.
// The jOOQ-codegen-gradle plugin has been introduced in version 3.19 only.
generationTool {
generator {
database {
name = "org.jooq.meta.extensions.liquibase.LiquibaseDatabase"
properties {
// Specify the root path, e.g. a path in your Maven directory layout
property {
key = "rootPath"
value = "${basedir}/src/main/resources"
}
// Specify the relative path location of your XML, YAML, or JSON script.
property {
key = "scripts"
value = "database.xml"
}
}
}
}
}
See the configuration XSD and gradle code generation for more details.
Dependencies
Note that the org.jooq.meta.extensions.liquibase.LiquibaseDatabase class is located in an external dependency, which needs to be placed on the classpath of the jOOQ code generator. E.g. using Maven:
<dependency>
<!-- Use org.jooq for the Open Source Edition
org.jooq.pro for commercial editions with Java 17 support,
org.jooq.pro-java-11 for commercial editions with Java 11 support,
org.jooq.pro-java-8 for commercial editions with Java 8 support,
org.jooq.trial for the free trial edition with Java 17 support,
org.jooq.trial-java-11 for the free trial edition with Java 11 support,
org.jooq.trial-java-8 for the free trial edition with Java 8 support
Note: Only the Open Source Edition is hosted on Maven Central.
Install the others locally using the provided scripts, or access them from here: https://repo.jooq.org
See the JDK version support matrix here: https://www.jooq.org/download/support-matrix-jdk -->
<groupId>org.jooq</groupId>
<artifactId>jooq-meta-extensions-liquibase</artifactId>
<version>3.16.23</version>
</dependency>
dependencies {
// Use org.jooq for the Open Source Edition
// org.jooq.pro for commercial editions with Java 17 support,
// org.jooq.pro-java-11 for commercial editions with Java 11 support,
// org.jooq.pro-java-8 for commercial editions with Java 8 support,
// org.jooq.trial for the free trial edition with Java 17 support,
// org.jooq.trial-java-11 for the free trial edition with Java 11 support,
// org.jooq.trial-java-8 for the free trial edition with Java 8 support
//
// Note: Only the Open Source Edition is hosted on Maven Central.
// Install the others locally using the provided scripts, or access them from here: https://repo.jooq.org
// See the JDK version support matrix here: https://www.jooq.org/download/support-matrix-jdk
implementation("org.jooq:jooq-meta-extensions-liquibase:3.16.23")
}
dependencies {
// Use org.jooq for the Open Source Edition
// org.jooq.pro for commercial editions with Java 17 support,
// org.jooq.pro-java-11 for commercial editions with Java 11 support,
// org.jooq.pro-java-8 for commercial editions with Java 8 support,
// org.jooq.trial for the free trial edition with Java 17 support,
// org.jooq.trial-java-11 for the free trial edition with Java 11 support,
// org.jooq.trial-java-8 for the free trial edition with Java 8 support
//
// Note: Only the Open Source Edition is hosted on Maven Central.
// Install the others locally using the provided scripts, or access them from here: https://repo.jooq.org
// See the JDK version support matrix here: https://www.jooq.org/download/support-matrix-jdk
implementation "org.jooq:jooq-meta-extensions-liquibase:3.16.23"
}
Additional dependencies may be required by liquibase, e.g. when using YAML. Please refer to the liquibase documentation about additional dependencies.
Vendor specific features
The LiquibaseDatabase simulates your migration in memory and may thus not support all vendor specific features of your target dialect. If you run into such limitations, know that it is just a "quick-and-dirty" approach to such a simulation. Running an actual migration on your actual target RDBMS (e.g. using testcontainers) will be more reliable. An example of this approach is given here: https://blog.jooq.org/using-testcontainers-to-generate-jooq-code/.
Feedback
Do you have any feedback about this page? We'd love to hear it!