Tutorial: Quick & Dirty Liquibase with Maven/MySQL

Already using Maven & MySQL? You’re in luck! It only takes five easy steps to use Liquibase on your project. This tutorial covers the minimal steps required to get set up using Liquibase.

In a previous post, I made the case for why every developer needs Liquibase in their toolkit. This tutorial will demonstrate the ease with which you can adopt Liquibase into your workflow.

Like I’ve done on many projects, I have a local MySQL server running on my development machine. That makes testing easier. You could use this same approach to connect to a MySQL DB anywhere, like AWS or Google Cloud. For this tutorial, I’m keeping it simple to demonstrate how easy adding Liquibase to a project can be.

This tutorial assumes:

1. A pom.xml exists at the root of your <project> directory.
2. The <project> uses the typical Maven structure, e.g. production code lives in <project>/src/main/java/… and text resources live in <project>/src/main/resources/…
3. A username and password exist for the database with the right permissions for creating and dropping tables.

Now let’s dive in. It’s a simple 5 steps.

Step 1. Create a place for Liquibase files

Make a directory for database stuff and changelogs:

mkdir <project>/src/main/resources/db
mkdir <project>/src/main/resources/db/changelog

Step 2. Set up your Liquibase properties file

Liquibase uses a properties file to store information about your database connection and any additional settings you may need. Ours will be simple, only requiring four settings.

Create a text file named liquibase.properties in the <project>/src/main/resources/db directory. Edit the file to add four lines to specify the changeLogFile location, the database connection URL, and the username and password for the database.

changeLogFile: src/main/resources/db/changelog/db.changelog-master.yaml
url: jdbc:mysql://localhost:3306/myapp
username: my_username
password: my_password

Step 3. Create your first change set

A change set is a group of changes that should be applied to your database as a single unit. Next, let's specify a change to the database by adding it to the changelog. In the previous step, we said the changeLogFile would be in src/main/resources/db/changelog/db.changelog-master.yaml. We edit that file and add a change to use while testing out Liquibase. Note that we are using the YAML format, which I prefer because it’s terse. Liquibase supports other formats like XML, JSON, SQL, etc.

databaseChangeLog:
- changeSet:
    id: 1
    author: myname
    changes:
    - createTable:
        tableName: person_test
        columns:
        - column:
            autoIncrement: true
            constraints: {nullable: false, primaryKey: true}
            name: id
            type: int
        - column:
            constraints: {nullable: false}
            name: name
            type: varchar(255)
        - column:
            constraints: {nullable: false}
            name: email
            type: varchar(255)

Step 4. Add Liquibase to Maven

Now that we have the liquibase.properties file in place and our first change specified, we are ready to update our Maven pom.xml to include Liquibase. Edit the pom.xml to add the liquibase-maven-plugin to the plugins section of your build section.

<project>
...
  <build>
    <plugins>
      ... 
      <plugin>
        <groupId>org.liquibase</groupId>
        <artifactId>liquibase-maven-plugin</artifactId>
        <configuration>
          <propertyFile>src/main/resources/db/liquibase.properties</propertyFile>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

And if you don’t already have the mysql-connector-java dependency included in your pom.xml, add it now.

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
      <version>8.0.31</version>
    </dependency>
  </dependencies>
  ...
</project>

Step 5. Run Liquibase

We are ready to run our first Liquibase command with Maven. First, run the liquibase:update command to add the new person_test table to the database.

> mvn liquibase:update

Then, I like to look at the database. For my satisfaction, I like to make sure that the new table got added. Since I have the MySQL server running locally, I can run a simple command to show the tables and describe the new person_test table.

> mysql -u my_username -p myapp -e "show tables; desc person_test;"
+-----------------------+
| Tables_in_myapp       |
+-----------------------+
| ...                   |
| person_test           |
| ...                   |
+-----------------------+
+-------+--------------+------+-----+---------+----------------+
| Field | Type         | Null | Key | Default | Extra          |
+-------+--------------+------+-----+---------+----------------+
| id    | int          | NO   | PRI | NULL    | auto_increment |
| name  | varchar(255) | NO   |     | NULL    |                |
| email | varchar(255) | NO   |     | NULL    |                |
+-------+--------------+------+-----+---------+----------------+

Voila! The new table exists and has the three fields we specified in our changeset. That’s how easy it is to set up and run with Liquibase.

We don’t want to keep our person_test table, though. That was just for testing. Liquibase makes it easy to roll back changes to the database. Let’s roll back that change.

> mvn liquibase:rollback -Dliquibase.rollbackCount=1

As you continue to develop your project, you can add additional change sets as needed to track and apply changes to your database. Simply add new change sets to your change log file and run the update command to apply the changes to the database.

And that’s it! You’re now up and running with Liquibase. With this tool, you’ll be able to easily track and manage changes to your database schema, making your development process more efficient and streamlined. Happy coding!

Watch a video of this tutorial on Loom

Find out more about Liquibase

Find out more about Liquibase with Maven

Find out more about Liquibase with MySQL