What support does Liquibase have for Docker?

Liquibase Secure Docker container image

Our Liquibase Secure Docker Official Image is available with Liquibase 5.0 and newer. We recommend that all users use this image for the latest updates and support.

Liquibase Docker container image includes the Liquibase software, Java, JDBC drivers, and all other dependencies already preconfigured. The image is based on the Eclipse Temurin image eclipse-temurin:17-jre-focal.

Also, there are libraries represented by database driver and client packages that are preinstalled into the container image:

• Big Query

• DB2

• Firebird

• H2

• MariaDB

• MongoDB

• MS SQL Server

• Oracle

• PostgreSQL

• Snowflake

• SQLite

• Sybase

Note: The database driver for MySQL is not preinstalled into the container image and require additional steps to install.

See the Liquibase Dockerfile for more details.

Docker pull command: docker pull liquibase

Example JDBC URLs

Supported tags

Tags

The following tags are officially supported:

• Overall most recent build: The latest tag is kept up to date with the most advanced Liquibase release: latest.

• Latest major or minor builds: These tags are kept up to date with the most recent patch release of each stream, such as 4.23.

• Specific releases: Each specific release has an associated tag, such as 4.23.1.

Here is a full list of available tags.

Changelog files

The docker image has a /liquibase/changelog volume in which the directory that contains the root of your changelog tree can be mounted. Your --changelog-file attribute should include the path relative to the volume.

You can also use the /liquibase/changelog volume for commands that create output files, such as generate-changelog. In this case, you must specify the absolute path to the changelog; prefix the path with /liquibase/changelog/<PATH TO CHANGELOG FILE>.

Example

If you have a local /path/to/changelog:/liquibase/changelog liquibase/changelog.xml file, you can run:

docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase-secure --changeLogFile=changelog.xml update

To generate a new changelog file at this location, run:

docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase-secure liquibase generate-changelog

Configuration files

If you use a Liquibase properties file (defaults file) like liquibase.properties to specify attributes instead of passing them on the command line, include it in your changelog volume mount and reference it when running commands.

When you specify a custom Liquibase properties file, ensure you include the relative file path to the /liquibase/liquibase-secure.properties volume so that Liquibase can continue looking for your properties file there.

Example

If you have a local /path/to/liquibase.properties:/liquibase/liquibase-secure.properties liquibase/liquibase-secure.properties file, where liquibase.properties represents the Liquibase properties file, run the following command:

docker run --rm -v /path/to/liquibase.properties:/liquibase/liquibase-secure.properties/liquibase --defaultsFile=liquibase.properties update

MySQL driver

The JDBC driver for MySQL has licensing restrictions that prevent it from being preinstalled into the container image. You must load the driver in one of the following ways:

Dockerfile:

1. Download MySQL driver

2. Place the driver in your /lib folder in the Docker image.

3. Then enter this command in the CLI:

docker build . -t liquibase-mysql

For more information, see docker build.

Set the environment variable at runtime

1. Alternatively, enter this command in the CLI:

docker run -e INSTALL_MYSQL=true liquibase update

For more information, see Docker run reference § ENV (environment variables).

Complete examples

Command line

1. Specifying everything using arguments:

docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase --license-key="<PASTE LB Secure LICENSE KEY HERE>" update --url=jdbc:postgresql://<IP OR HOSTNAME>:5432/<DATABASE>?currentSchema=<SCHEMA NAME> --changelog-file=com/example/changelog.xml --username=<USERNAME> --password=<PASSWORD>

2. Using with Liquibase environment variables example:

docker run --env LIQUIBASE_COMMAND_USERNAME --env LIQUIBASE_COMMAND_PASSWORD --env LIQUIBASE_COMMAND_URL --env LIQUIBASE_PRO_LICENSE_KEY --env LIQUIBASE_COMMAND_CHANGELOG_FILE --rm -v <PATH TO CHANGELOG DIR>/changelogs:/liquibase/changelog liquibase --log-level=info update

Properties file

Use the following example for configuring the liquibase.docker.properties file

classpath: /liquibase/changelog url: jdbc:postgresql://<IP OR HOSTNAME>:5432/<DATABASE>?currentSchema=<SCHEMA NAME> changelog-file: changelog.xml username: <USERNAME> password: <PASSWORD> licenseKey=<PASTE LB SECURE LICENSE KEY HERE>

Use the --defaults-file parameter to invoke the liquibase.docker.properties file when running commands in the CLI:

docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase/--defaults-file=/liquibase/changelog/liquibase.docker.properties update

Troubleshooting issues with Liquibase and Docker

If you use the Liquibase Docker image 4.3.5 with Aurora MySQL RDS Cluster and have issues with the connection link, add ?autoReconnect=true"&"useSSL=false to the end of the database name in your URL:

--url=jdbc:mysql://devops-test.us-east-2.rds.amazonaws.com:3306/auditsource?autoReconnect=true"&"useSSL=false