Micronaut Liquibase

Integration between Micronaut and Liquibase

Version:

1 Introduction

The Micronaut Liquibase integration runs Liquibase changelogs. It does not create changelogs.

To use the Micronaut’s integration with Liquibase you must have the micronaut-liquibase dependency on your classpath:

implementation("io.micronaut.liquibase:micronaut-liquibase")
<dependency>
    <groupId>io.micronaut.liquibase</groupId>
    <artifactId>micronaut-liquibase</artifactId>
</dependency>

2 Release History

For this project, you can find a list of releases (with release notes) here:

3 Configuration

You can define liquibase configuration for each datasource. The following example demonstrates using it:

src/main/resources/application.yml
datasources:
    default: (3)
        url: 'jdbc:h2:mem:liquibaseDisabledDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE'
        username: 'sa'
        password: ''
        driverClassName: 'org.h2.Driver'
jpa:
    default: (3)
        packages-to-scan:
            - 'example.micronaut'
        properties:
            hibernate:
                hbm2ddl:
                    auto: none (1)
                show_sql: true
liquibase:
    datasources: (2)
        default: (3)
            change-log: 'classpath:db/liquibase-changelog.xml' (4)
1 Disable schema DDL creation.
2 Define all liquibase configuration under key liquibase.datasources.
3 Configure liquibase configuration for default data source.
4 Root changelog under src/main/resources/db/liquibase-changelog.xml.

Often, you will have a root changelog:

resources/db/liquibase-changelog.xml
<?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.1.xsd">
  <include file="changelog/01-create-books-schema.xml" relativeToChangelogFile="true"/>
  <include file="changelog/02-insert-data-books.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

which imports changelogs which you keep generating as your app evolves:

resources/db/changelog/01-create-books-schema.xml
<?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.1.xsd">
  <changeSet id="01" author="sdelamo">
    <createTable tableName="books"
      remarks="A table to contain all books">
      <column name="id" type="int">
        <constraints nullable="false" unique="true" primaryKey="true"/>
      </column>
      <column name="name" type="varchar(255)">
        <constraints nullable="false" unique="true"/>
      </column>
    </createTable>
  </changeSet>
</databaseChangeLog>
Liquibase migrations are executed when datasources are created. Because Micronaut beans are, by default, created lazily, if you do not inject a Datasource somewhere, then migrations are not executed. This may be the case when you create a command in a separate module just to run migrations, e.g. using Micronaut support for picocli. In this case it is enough to inject a Datasource in anyone of your singletons and migrations will be executed.

Run migrations manually

If you need more control to decide when the migrations are executed it is possible to configure the application like this:

liquibase:
  enabled: true (1)
  datasources:
    default:
      enabled: false (2)
1 Liquibase needs to be enabled
2 Disable liquibase migrations for your specific datasource

Now you can inject the LiquibaseMigrator bean and call manually the method run to execute the migrations when you want.

There are several options available for configuration:

🔗
Table 1. Configuration Properties for LiquibaseConfigurationProperties
Property Type Description

liquibase.datasources.*.async

boolean

Whether liquibase operations should be run asynchronously.

liquibase.datasources.*.enabled

boolean

Sets whether this liquibase configuration is enabled. Default value (true).

liquibase.datasources.*.change-log

java.lang.String

Change log configuration path.

liquibase.datasources.*.default-schema

java.lang.String

Default database schema.

liquibase.datasources.*.liquibase-schema

java.lang.String

Schema to use for Liquibase objects.

liquibase.datasources.*.drop-first

boolean

Whether to first drop the database schema. Default value (false).

liquibase.datasources.*.liquibase-tablespace

java.lang.String

Tablespace to use for Liquibase objects.

liquibase.datasources.*.database-change-log-table

java.lang.String

Name of table to use for tracking change history.

liquibase.datasources.*.database-change-log-lock-table

java.lang.String

Name of table to use for tracking concurrent Liquibase usage.

liquibase.datasources.*.tag

java.lang.String

a tag.

liquibase.datasources.*.contexts

java.lang.String

Comma-separated list of runtime contexts to use.

liquibase.datasources.*.labels

java.lang.String

Comma-separated list of runtime labels to use.

liquibase.datasources.*.test-rollback-on-update

boolean

Whether rollback should be tested before update is performed. Default value (false).

liquibase.datasources.*.rollback-file-path

java.lang.String

Path to file to which rollback SQL is written when an update is performed.

liquibase.datasources.*.parameters

java.util.Map

Change log parameters.

liquibase.datasources.*.ignore-classpath-prefix

boolean

Ignores classpath prefix during changeset comparison.

Logging

Liquibase 4.0 has changed how logging is done and now it is based on Java Util Logging (JUL). This means that without doing anything the log format won’t be the usual in Micronaut:

16:39:58.744 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
16:39:58.945 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
Nov 10, 2020 4:39:59 PM liquibase.lockservice
INFO: Successfully acquired change log lock
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: Creating database history table with name: PUBLIC.DATABASECHANGELOG
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: Reading from PUBLIC.DATABASECHANGELOG
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: Table users created
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: ChangeSet db/changelog/01-create-users-table.xml::01::ilopmar ran successfully in 10ms
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: New row inserted into users
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: New row inserted into users
Nov 10, 2020 4:39:59 PM liquibase.changelog
INFO: ChangeSet db/changelog/02-insert-users-data.xml::02::ilopmar ran successfully in 4ms
Nov 10, 2020 4:39:59 PM liquibase.lockservice
INFO: Successfully released change log lock
16:40:00.277 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 2392ms. Server Running: http://localhost:8080

If you want to integrate JUL and Logback you need to do the following in your application:

  • Add the dependency:

implementation("org.slf4j:jul-to-slf4j:1.7.30")
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>jul-to-slf4j</artifactId>
    <version>1.7.30</version>
</dependency>

  • Add the following contextListener to your logback.xml:

src/main/resources/logback.xml
<configuration>

    <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
        <resetJUL>true</resetJUL>
    </contextListener>

    <appender ...>
        ...
    </appender>

    ...

</configuration>
  • Initialize the JUL to Slf4j bridge. You can add the following to your Application class:

src/main/java/my/package/Application.java
public static void main(String[] args) {
    // Bridge JUL to Slf4j
    SLF4JBridgeHandler.removeHandlersForRootLogger();
    SLF4JBridgeHandler.install();

    Micronaut.run(Application.class, args);
}

With the previous configuration, starting your application again will show the logs properly:

16:47:10.868 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
16:47:11.042 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
16:47:11.344 [main] INFO  liquibase.lockservice - Successfully acquired change log lock
16:47:11.744 [main] INFO  liquibase.changelog - Creating database history table with name: PUBLIC.DATABASECHANGELOG
16:47:11.747 [main] INFO  liquibase.changelog - Reading from PUBLIC.DATABASECHANGELOG
16:47:11.844 [main] INFO  liquibase.changelog - Table users created
16:47:11.844 [main] INFO  liquibase.changelog - ChangeSet db/changelog/01-create-users-table.xml::01::ilopmar ran successfully in 20ms
16:47:11.857 [main] INFO  liquibase.changelog - New row inserted into users
16:47:11.858 [main] INFO  liquibase.changelog - New row inserted into users
16:47:11.859 [main] INFO  liquibase.changelog - ChangeSet db/changelog/02-insert-users-data.xml::02::ilopmar ran successfully in 3ms
16:47:11.861 [main] INFO  liquibase.lockservice - Successfully released change log lock
16:47:12.288 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 2213ms. Server Running: http://localhost:8080

4 GORM Support

There is also support for running Liquibase migrations when using GORM.

1.- Add the dependency:

implementation("io.micronaut.groovy:micronaut-hibernate-gorm")
<dependency>
    <groupId>io.micronaut.groovy</groupId>
    <artifactId>micronaut-hibernate-gorm</artifactId>
</dependency>

2.- You also need at least one class annotated with @grails.gorm.annotation.Entity to trigger the migrations.

src/main/groovy/example/Book.groovy
package example

import grails.gorm.annotation.Entity

import io.micronaut.context.annotation.Requires

@Entity
class Book {
    String name
}

3.- Then it is necessary to configure GORM datasource:

src/main/resources/application.yml
dataSource: (1)
  pooled: true
  jmxExport: true
  dbCreate: none (2)
  url: 'jdbc:h2:mem:GORMDb'
  driverClassName: org.h2.Driver
  username: sa
  password: ''

liquibase:
  datasources: (3)
    default: (4)
      change-log: classpath:db/liquibase-changelog.xml (5)
1 Definition of the first data source in GORM. The name it’s default and it can’t be changed.
2 Disable schema DDL creation.
3 Define liquibase configuration under liquibase.datasources key.
4 Define liquibase configuration for the default datasource.
5 The migration file path is src/main/resources/db/liquibase-changelog.xml.

Multiple Data sources

It is also possible to configure Liquibase migrations with multiple data sources when using GORM:

src/main/resources/application.yml
dataSource: (1)
  pooled: true
  jmxExport: true
  dbCreate: none
  url: 'jdbc:h2:mem:liquibaseGORMDb'
  driverClassName: org.h2.Driver
  username: sa
  password: ''

dataSources:
  books: (2)
    pooled: true
    jmxExport: true
    dbCreate: none
    url: 'jdbc:h2:mem:liquibaseBooksDb'
    driverClassName: org.h2.Driver
    username: sa
    password: ''

liquibase:
  datasources:
    default: (3)
      change-log: classpath:db/liquibase-changelog.xml
    books: (4)
      change-log: classpath:db/liquibase-changelog.xml
1 Definition of the first data source in GORM. The name it’s default and it can’t be changed.
2 Name of the additional data source.
3 Define liquibase configuration for the default datasource.
4 Define liquibase configuration for the books datasource.
For more information about how to configure GORM, take a look at the documentation.

5 GraalVM support

Micronaut Liquibase is compatible with GraalVM so it is possible to create native images and run the migrations during application startup.

Everything is handled automatically by the library so users don’t need any special configuration.

See the section on GraalVM in the user guide for more information.

6 Endpoint

This configuration provides a built-in endpoint to expose all the applied migrations in /liquibase.

To enable the endpoint add the following to the configuration:

resources/application.yml
endpoints:
    liquibase:
        enabled: true (1)
        sensitive: false (2)
1 /liquibase endpoint is enabled.
2 /liquibase endpoint is open for unauthenticated access.
$ curl http://localhost:8080/liquibase

[{
    "name": "default",
    "changeSets": [{
        "author": "sdelamo",
        "changeLog": "classpath:db/changelog/01-create-books-and-author-schema.xml",
        "comments": "",
        "contexts": [],
        "dateExecuted": "2018-10-29T16:33:05Z",
        "deploymentId": "0830784929",
        "description": "createTable tableName=books; createTable tableName=authors; addForeignKeyConstraint baseTableName=books, constraintName=author_fk, referencedTableName=authors",
        "execType": "EXECUTED",
        "id": "01",
        "labels": [],
        "checksum": "8:140eb966bb6a14bccade2c2d9133b7d3",
        "orderExecuted": 1,
        "tag": "tag1"
    }, {
        "author": "sdelamo",
        "changeLog": "classpath:db/changelog/02-insert-data-authors.xml",
        "comments": "Inserting Authors",
        "contexts": [],
        "dateExecuted": "2018-10-29T16:33:05Z",
        "deploymentId": "0830784929",
        "description": "insert tableName=authors; insert tableName=authors; insert tableName=authors; insert tableName=authors; insert tableName=authors",
        "execType": "EXECUTED",
        "id": "02",
        "labels": [],
        "checksum": "8:6204c525ce5c1c55f064888d078b8f05",
        "orderExecuted": 2,
        "tag": null
    }]
}]
See the section on Built-in endpoints in the user guide for more information.

7 Repository

You can find the source code of this project in this repository: