Using Liquibase and Docker
Docker is an open platform for developing, shipping, and running applications. Docker provides the ability to package and run an application in a loosely isolated environment called a container. You can also create and use images, networks, volumes, plugins, and other objects. For more information, see Docker's overview.
If you use a virtual machine, it requires a separate copy of the operating system, which needs space. Docker leverages the host system for the operating system to cut down on space. Additionally, Docker helps to start your application more quickly.
Liquibase Docker container image
Liquibase Docker container image includes the Liquibase software, Java, JDBC drivers, and all other dependencies already preconfigured. The image is based on a trusted OpenJDK image openjdk:11-jre-slim-buster
, which is based on a trusted OS image debian:buster-slim
.
Also, there are libraries represented by database driver and client packages that are preinstalled into the container image. The list of available database drivers:
- DB2
- Firebird
- MariaDB
- MSSQLServer
- MySQL
- PostgreSQL
- Snowflake
- SQLite
- Sybase
Note: See the Liquibase Dockerfile for more details.
You can find the official repository for Liquibase images on the download page.
Docker pull command:
docker pull liquibase/liquibase
Liquibase Docker supported tags
The following tags are officially supported:
- Overall most recent build: The latest tag will be 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.5
. - Specific releases: Each specific release has an associated tag, such as
4.4.3
.
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
.
Example
If you have a local c:\projects\my-project\src\main\resources\com\example\changelogs\root.changelog.xml
file, you can run:
docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase
--changelog-file=com/example/changelogs/root.changelog.xml update
Configuration files
If you use a Liquibase properties 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 classpath=/liquibase/changelog
so that Liquibase can continue looking for your changelog files there.
Example
If you have a local c:\projects\my-project\src\main\resources\liquibase.properties
file, where liquibase.properties
represents the Liquibase properties file, run the following command:
docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase
--defaultsFile=/liquibase/changelog/liquibase.properties update
Drivers and extensions
The Liquibase docker container includes drivers for many databases. If your driver is not included or if you have an extension, you can mount a local directory that contains .jar
files to /liquibase/classpath
and add .jar
files to your classpath setting.
Example
If you have a local c:\projects\my-project\lib\my-driver.jar
file, you run the following command:
docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog -v c:\projects\my-project\lib:/liquibase/classpath liquibase/liquibase
--classpath=liquibase/changelog:liquibase/classpath/my-driver.jar update
Best practices
- Specify everything by using arguments
docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase/liquibase
--url=jdbc:postgresql://<IP OR HOSTNAME>:5432/<DATABASE>?currentSchema=<SCHEMA NAME>
--changelog-file=com/example/changelog.xml --username=<USERNAME>
--password=<PASSWORD> --liquibaseProLicenseKey="<PASTE LB PRO LICENSE KEY HERE>" update
- 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>
liquibaseProLicenseKey=<PASTE LB PRO LICENSE KEY HERE>
- Use the
--defaultsFile
argument to evoke theliquibase.docker.properties
file when running commands in the CLI
docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase/liquibase
--defaultsFile=/liquibase/changelog/liquibase.docker.properties update
Example JDBC URLs
Database | JDBC URL |
---|---|
MS SQL Server |
|
PostgreSQL |
|
MySQL |
|
MariaDB |
|
DB2 | jdbc:db2://<IP OR HOSTNAME>:50000/<DATABASE>
|
Snowflake | jdbc:snowflake://<IP OR HOSTNAME>/?db=<DATABASE>&schema=<SCHEMA NAME>
|
Sybase | jdbc:jtds:sybase://<IP OR HOSTNAME>:/<DATABASE>
|
SQLite |
|
An example of using Liquibase and PostgreSQL with Docker
When you start a PostgreSQL database using docker run postgres
, the command looks at the local system to see if the PostgreSQL Docker container already exists. If the container doesn’t exist, the command will refer to Docker Hub and download it.
To run PostgreSQL and Liquibase, your Liquibase changelog needs to be accessible to the Docker container. Mount the directory that includes the changelog file with the -v
option:
docker run -v /home/changelog:/liquibase/changelog liquibase/liquibase
--url=jdbc:postgresql://<DATABASE_IP>:5432/postgres
--changelog-file=/liquibase/changelog/changelog.xml --username=postgres
--password=postgres
Note: Enter the directory that contains your changelog in place of /home/changelog
. Also, enter the hostname/ip
of your database. If you are running PostgreSQL as a Docker container, use docker inspect <CONTAINER_NAME>
to find the IP address of your PostgreSQL database.
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