July 29, 2020

6 Reasons to Use Liquibase with Docker

Updated January 11, 2022

Docker is super awesome for running machines that were previously used via virtual machines — but each virtual machine requires a separate copy of the operating system. That’s a lot of space! Docker leverages the host system for the operating system to cut down on space. Docker also makes it really fast to start those machines. There are also advantages to using a tool like Liquibase from your Docker container. In this blog, we’ll cover the six most common reasons we’ve heard from the Liquibase community about why they use Docker to run Liquibase.

Why Use the Liquibase Docker Image?

There are several reasons why you might want to take advantage of the Liquibase Docker image:

  1. You already have Docker for your development databases. This makes it very easy to use the Liquibase Docker image available in Docker Hub.
  2. You want to use Liquibase on different operating systems.
  3. You want to easily try out and switch between different versions of Liquibase.
  4. You want to update your database code at the same time as your application code. Regardless of the application code, meaning if you use .NET, Python, Java, or some other programming language, you can use Docker to update your database code at the same time as your application code.
  5. You want to easily get Liquibase into CI/CD tools.
  6. You want a super simple way to get started with Liquibase.

Let’s dive deeper into a couple of the reasons listed above…

Switching Between Using Liquibase on Different Operating Systems

One benefit of using Liquibase on Docker is that the operating system behind the scenes will not matter since Docker runs on MacOS, Windows, and Linux OSes. The only difference between executing your commands will be the mount points you use for your Liquibase files: C:\liquibase\changelog vs. /liquibase/changelog.

If you don’t use mount points, the commands will be the same across different operating systems. To provide another example:

docker run -v /users/mikeo/liquibase:/liquibase/changelog status 

This command works on Windows, Linux, and MacOS.

Easily Try New Versions of Liquibase

Using Docker also allows you to try different versions of Liquibase easily. It’s super simple to use the latest version of Liquibase:

image: liquibase/liquibase:latest

This line can easily be changed to the following to change between Liquibase versions:

image: liquibase/liquibase:4.6.1


image: liquibase/liquibase:4.7.0

This gives you a simple way to upgrade versions whenever you’d like.

Easily Get Liquibase into CI/CD Tools

Docker is available out of the box with various CI/CD tools:

  • GitLab
  • GitHub Actions
  • Jenkins
  • AWS Code Pipelines
  • Azure DevOps
  • Travis CI

You can access the Docker container by adding a single line. For example, in Gitlab all that is required is a simple line of code like the following:

image: liquibase/liquibase:latest

See this code in action in an example GitLab repository .yml file.

A Super Easy Way to Get Started with Liquibase

To give a specific demonstration, you can easily start a PostgreSQL database using docker run postgres. This looks at the local system to see if the PostgreSQL Docker container already exists. If not, it will go to Docker Hub and download it. Neat! We can also do the same for utilities like Liquibase. The only difference is that the Liquibase Docker container will run Liquibase and exit. Unlike a long-running server process, like PostgreSQL, it doesn’t need to be running all the time. The value of this is that you might need to run Liquibase from a system that does not have Liquibase installed but does have Docker. Here’s the documentation.

Quick example of using Liquibase via Docker with PostgreSQL

Here’s a quick example of how to use it with PostgreSQL.

  1. Start your Docker instance of PostgreSQL or have the connection information to connect to an existing image:
docker run postgres -e POSTGRES_PASSWORD=yourpassword
  1. Your Liquibase changelog needs to be accessible to the Docker container. So, we’ll mount the directory that holds that file with the -v option. Here’s the command:
docker run -v /home/mikeo/changelog:/liquibase/changelog liquibase/liquibase --url=”jdbc:postgresql://<DATABASE_IP>:5432/postgres” --changeLogFile=./changelog/changelog.sql --username=postgres --password=yourpassword update
  1. There are only two things you need to change in the above command:
  • Update  /home/mikeo/changelog directory to the directory that contains your main changelog file
  • Enter the hostname/ip and username/password of your database

Bonus fun: If you are running PostgreSQL as a docker container, use docker inspect <CONTAINER_NAME> to find the IP address of your PostgreSQL database.

Let us know if you use Liquibase with Docker and run into any issues! You can always chat with us on our forum.

Summing It Up

We’ve received a lot of great feedback from both long-time Liquibase users and new Liquibase users taking advantage of this integration with Docker. For more information about using Docker with Liquibase, check out the recording of our community meetup where we went through a quick demo and covered tips and tricks.
If you have any comments or questions about using Liquibase with Docker, don’t hesitate to post about it on the Liquibase forum. Want to contribute to this open source integration? Make a pull request or feature request in our repository.

Share on: