Liquibase in a Gradle project

gradleTasks smallLiquibase is great for managing database scripts and tasks like upgrading, rolling back, verification. If you have an automated building and deployment process, you would like to include Liquibase tasks in it. If, by any chance, the project is Gradle-based and the above tasks run proper Gradle tasks, the best option would be to use Gradle for handling Liquibase too. That is possible and I would like to share with you the way how it can be done using liquibase-gradle-plugin.



Gradle-based building process

If your project is based on Gradle, automating the building process is very easy. Most probably, the building process with Gradle wrapper is done by a command similar to the one below:

gradlew clean build test

It is extremly simple. Each execution of this command, builds a new package that is complete and unit tested. Such job could be scheduled to run each night on the latest sources. If the built application should be deployed on some kind of an integration environment then the whole process can be chained:

  • Step 1 - Build.
  • Step 2 - Deploy if Step 1 succeeded.

Such chain of actions can be configured using Jenkins or Team City, but that is not the subject of this article. Going back to the main topic, if the deployment requires a database update, it becomes more complex. Fortunately, if you already use Liquibase for managing database structure, only one small step is missing to include a database update into the automated deployment process.


Add liquibase-gradle-plugin into the project

Initially Liquibase plugin for Gradle was developed independently from Nathan Voxland who is the Liquibase author. Tim Berglund started the project and then it was passed to and is still continued by Steve Saliman. Those gentlemen have done a great job and the plugin is a reliable bridge between Gradle and Liquibase.

It can be included in a project by adding a dependency in the buildscript section of build.gradle in your project:

buildscript {
repositories {
dependencies {
classpath 'org.liquibase:liquibase-gradle-plugin:1.1.1'

Then, the plugin can be applied by using apply plugin in the build.gradle file:

apply plugin: 'org.liquibase.gradle'

After refreshing the Gradle project, Liquibase tasks show up.


In result, two libraries are downloaded from Maven repository:

  • liquibase-gradle-plugin 1.1.1
  • liquibase-core 3.3.5

Now, if Liquibase is configured properly (paths to the change log scripts, database connection string, credentials etc.), Gradle can update the database by running:

gradlew update

The plugin allows running probably all Liquibase commands from Gradle.


Force liquibase-gradle-plugin to run with the latest liquibase-core

At the time of writting this article, the latest liquibase-gradle-plugin, which is v.1.1.1, is dependent on liquibase-core 3.3.5. However, there is already liquibase-core 3.4.0 available with some important bug fixes. In spite of there is no official liquibase-gradle-plugin available that would be dependent on liquibase-core 3.4.0, Gradle allows overriding it.

Here it is how build.gradle can be configured to use the latest core version (3.4.0) with the latest plugin (1.1.1).

buildscript {
repositories {
dependencies {
classpath('org.liquibase:liquibase-gradle-plugin:1.1.1') {
exclude(module: 'liquibase-core') // exclude the dependency on liquibase-core:3.3.5

plugin: 'org.liquibase.gradle'

The default liquibase-core is excluded from the dependencies of liquibase-gradle-plugin. Instead of that, it is manually added as 3.4.0 version.

After refreshing Gradle tasks, needed libraries are downloaded and added to the project.

This is a Gradle way of using dependent modules in versions that are not officially stated as compatible. Of course, it is not safe to do this as it may result in some incompatibility errors but I did that and liquibase-gradle-plugin 1.1.1 works well with liquibase-core 3.4.0. Is it worth taking the risk? It depends on:

  • how much you can loose
  • whether you can wait on the officially compatible liquibase-gradle-plugin or not

I needed bug fixes from 3.4.0 so went into it and I do not regret.