Skip to Content

Getting Started With Liquibase

I’ve always wanted to try a change management system for the database but never had the opportunity. Most jobs we were using SQL scripts embedded in ColdFusion files or a static set of SQL files which were run manually.

In my current job I was given the opportunity to implement a solution and after a bit of research I decided on Liquibase. It’s been around a long time and is well documented.

I won’t get into too many details here on how to use it. Just some of the decisions we made and some tips and links to resources I found useful while learning.

In most dynamic websites you make changes to two things:

  1. Your code
  2. Your database

Most of us (hopefully) keep our code in some sort of version control system like Git, but often the database is left out of the loop. In reality though our code changes are frequently tied to database changes so we should be tracking changes in both!

  • You add a table in release 1.
  • You add a column in release 2.
  • You remove some data in release 3.
  • And if something goes wrong in release 3 you can easily roll back both your code (in Git), and your database changes (via Liquibase).

Getting started was easy. Download the Liquibase installer (it’s Java), configure your datasource via a simple property file and you should be able to start interacting with your database. The Liquibase quick start guide steps you through everything.

At this point I would stop because you need to make some decisions on how you are going to track your database changes.

To learn more I would encourage you to visit the Liquibase University and take the two beginner courses. The classes will guide you through decisions on why you should use Liquibase, what format to choose for your changelogs, how to organize your files and much more.

They go over everything you need as a beginner and as you learn more you can also explore the Intermediate subjects as well. These can all be viewed within a day so it’s not a terrible time commitment and the information they present is invaluable.

For our needs we ended up chosing to use simple SQL changelogs. You can create changelogs in .xml, .sql, .json, or .yaml formats but I did not really see an advantage to using one of the more verbose choices.

A simple SQL example of a Liquibase changelog:

-- liquibase formatted sql

-- changeset liquibase:1
CREATE TABLE test_table (test_id INT, test_column VARCHAR(256), PRIMARY KEY (test_id))

The other options can be much more verbose. The same example as above in 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"
	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-latest.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-latest.xsd">
    <changeSet id="1" author="Liquibase">
    <createTable tableName="test_table">
           <column name="test_id" type="int">
                 <constraints primaryKey="true"/>
           </column>
           <column name="test_column" type="varchar"/>
    </createTable>
    </changeSet>
</databaseChangeLog>

The Liquibase docs are usually really good about providing examples in all available formats, and letting you know when something is supported in one format but not the other.

Liquibase also offers a “Pro” solution with brings some advanced features but I would suggest starting off with the free version and see if it will meet your needs.

We’ve been using Liquibase now for about six months and so far haven’t really had any major hickups. It’s nice to roll out changes during deployments knowing we can easily roll back things if necessary.

Next I’ll post how I built a CommandBox runner to help run Liquibase scripts in our quirky environment.