Integrate Liquibase with the pipeline using Gradle

Published in

Destination AARhus-TechBlog

4 min readNov 16, 2022

In this article, I will introduce a step-by-step guide to integrate Liquibase with the pipeline using a Liquibase Gradle plugin and hereby paving the way for continuous integrated database changes.

Are you experiencing challenges when deploying database changes? Do you have to communicate with an entirely different department to get through with changes? This can cause waiting time and perhaps even misunderstandings. Furthermore, where do you keep revisions other than in the sent mails?

The Liquibase integration will highly improve the revision of changes done to the database because the change log file can be kept in version control together with the Gradle project.

What is Liquibase?

Liquibase is a tool driven by a particular change log to manage all kinds of database statements, including insertion of rows into the table, creating and deletion of tables. The change log contains specific changesets, which can be written in SQL, XML, YAML or JSON providing a rich change log of the manipulation of the database. Here is an example of a change set written in SQL:

--liquibase formatted sql

--changeset user1:id1
CREATE TABLE Car (
id INT PRIMARY KEY,
make VARCHAR(100)
);

The first statement in the listing above indicates that the file is formatted in SQL, so that the parser can understand the SQL syntax.

The second statement defines the particular changeset with the username of the developer and a colon separates the id. The username of the developer and id together compose the primary key which have to be unique meaning that the developer has to generate a unique id for each changset. Therefore, an auto generated UUID is preferred to avoid primary key clashes in the “DATABASECHANGELOG” table, Liquibase creates in the database.

Lastly, the remaining lines are the SQL which is executed.

This example is the absolute bare minimum to include in an SQL formatted change log. For more attributes I refer to the documentation: https://docs.liquibase.com/concepts/changelogs/sql-format.html

How to integrate Liquibase using the Gradle plugin

In Figure 1, an overview of integrating Liquibase using the Gradle plugin is illustrated. The figure is composed of specific steps, respectively “1. Gradle project”, “2. Pipeline”, “3. Secrets” and “4. Database”.

Figure 1: Overview of integrating the Liquibase Gradle plugin

These four steps are presented in the following.

1. Gradle project

Firstly, a Gradle project is needed and in this step-by-step guide “gradle-6.7.1-all” is used. In the Gradle project, import the Liquibase Gradle plugin in build.gradle:

plugins {
  id 'org.liquibase.gradle' version '2.1.1'
}

Then add the following Liquibase runtime dependencies:

dependencies {
  liquibaseRuntime group: 'org.liquibase', name: 'liquibase-core', version: '4.2.2'
  liquibaseRuntime group: 'com.microsoft.sqlserver', name: 'mssql-jdbc', version: '10.2.0.jre11'
}

You can replace Microsoft SQL Server JDBC driver with that of MySQL, Oracle or others, cf. https://www.liquibase.com/supported-databases.

Next, add a Liquibase configuration in build.gradle so that arguments can be supplied from the command line:

liquibase {
  activities {
    def liquibaseUrl = project.hasProperty('liquibaseUrl') ? liquibaseUrl : null
    def liquibaseUsername = project.hasProperty('liquibaseUsername') ? liquibaseUsername : null
    def liquibasePassword = project.hasProperty('liquibasePassword') ? liquibasePassword : null
    main {
      changeLogFile 'change-log.sql'
      url liquibaseUrl
      username liquibaseUsername
      password liquibasePassword
    }
  }
}

The Gradle command

Now, the arguments can be supplied using the Gradle wrapper like this:

./gradlew update -PliquibaseUrl="<jdbc-connection-string>" -PliquibaseUsername="<jdbc-username>" -PliquibasePassword="<jdbc-password>"

Subsequently, place a change log file, including a change set, in the Gradle project folder where the Gradle wrapper also resides.

You can now try the command using a command line tool like Git Bash and verify that your changeset have been executed successfully before integrating the command with the pipeline. Be sure to execute the command in the Gradle project folder and be aware that Liquibase will execute the SQL statements written in the change set. Therefore, make sure that they are non-critical dummy changes which easily can be rolled back.

The remaining steps

Now “1. Gradle” from Figure 1 is done, the remaining steps are presented, which are “2. Pipeline”, “3. Secrets” and “4. Database”.

Firstly, when your Gradle project is done, use a pipeline which can be configured using your pipeline tool, e.g. Jenkins Pipeline or Azure Pipelines. In fact, this pipeline step can be configured at any pipeline step. The dedicated setup for the pipeline step is beyond scope of this article.

The pipeline uses secrets to access both username and password, as shown in Figure 1.

Lastly, the pipeline can be run with a specific Liquibase change set defined in the change log and hereby verify that the SQL in the change set has been executed successfully.

Conclusion

In this article, a step-by-step guide has been presented on how to integrate Liquibase with the pipeline using the Liquibase Gradle plugin and appertaining dependencies.

Furthermore, it has made our process of performing changes to our database easier as the previous process included ordering the database changes through mail to another department.

With this Liquibase integration, we can hereby perform database changes more rapidly and be more agile. We also know exactly how our database has been manipulated which provides us with more transparency and control!

About me

Hello! Thanks for reading! My name is Thomas Guldborg, and I am working as a Software Developer at Bankdata.