Set up liquibase on maven

Liquibase is an open-source library for managing database schema changes; it's database independent, so it works with any supported database engine.

Liquibase provides a Maven plugin to run database operations during the build process. In this post, I will show you a basic guide to configuring the liquibase plugin on your maven project, so let's go!.

Prerequisites

For this guide, I'm not going to go deep on creating a liquibase changelog. I'm focusing on how to set up the liquibase plugin.

You will need a supported database engine running and a clean database. For this project, I will use a dockerized PostgreSQL instance with a "test" database.

Create a new maven project

We'll use the quickstart archetype to create a new project:

mvn archetype:generate -DgroupId=dev.rcarrillo -DartifactId=liquibaseDemo -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

You can change the -DgroupId with any other group like my.project

This command will generate the following structure:

Define an initial database changeset

Create a folder to store our database changelog files:

mkdir dbchangelogs

Now create a changelog file and save it in the dbchangesets folder:

<?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"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xmlns:pro="http://www.liquibase.org/xml/ns/pro"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.3.xsd">

    <changeSet id="1" author="rcarrillo" labels="1.0.0" >
        <createTable tableName="games">
            <column name="id" type="int">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="varchar(100)">
                <constraints nullable="false"></constraints>
            </column>
        </createTable>
    </changeSet>
</databaseChangeLog>

master-changelog.xml

Final project structure, the changelogs folder is located in the root folder.

Add liquibase to the pom.xml file.

We have to update our pom.xml to add the liquibase plugin. I've removed the default plugins added by the archetype before adding the liquibase plugin:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dev.rcarrillo</groupId>
  <artifactId>liquibaseDemo</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>liquibaseDemo</name>
  <!-- FIXME change it to the project's website -->
  <url>http://www.example.com</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.liquibase</groupId>
          <artifactId>liquibase-maven-plugin</artifactId>
          <version>4.4.3</version>
          <configuration>
              <changeLogFile>dbchangelogs/master-changelog.xml</changeLogFile>
              <url> jdbc:postgresql://localhost:5432/test</url>
              <username>postgres</username>
              <password>yourPassword</password>
          </configuration>
          <dependencies>
              <dependency>
                  <groupId>org.postgresql</groupId>
                  <artifactId>postgresql</artifactId>
                  <version>42.3.0</version>
              </dependency>
          </dependencies>
          </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

The configuration section contains the parameters required to connect liquibase to our database.

changeLogFile: A relative path to the changelog file that I created in previous steps.
url: contains the JDBC URL specifying the driver (PostgreSQL, in this case), the host, and the database name
username: Our database username
password: Our password used to access the database

Please, please, never ever hardcode passwords on configuration files on the production environments, always prefer a mechanism like a secrets manager to hide your sensitive data.

Run maven with the liquibase plugin, and you're done.

Our setup is complete. We added liquibase to a maven project and configured the liquibase plugin to perform database changelogs in our Postgres server. The final step is just to run maven build specifying the liquibase operation that we want to achieve, in this case, update (if the database is empty, it will create the specified tables in the changelog).

mvn clean install -DskipTests liquibase:update

Once the build is complete, we can review our database and look for the table we've defined in the changelog file, plus a couple of liquibase tables used to manage the changelogs.