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 the Eclipse Temurin image
Also, there are libraries represented by database driver and client packages that are preinstalled into the container image. The list of available database drivers:
- MS SQL Server
Note: The database driver for MySQL is not preinstalled into the container image and requires additional steps to install. See MySQL driver.
Docker pull command:
docker pull liquibase/liquibase
Example JDBC URLs
|IBM DB2 LUW||
|Microsoft SQL Server||
Supported tags and image flavors
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 major or minor builds: These tags are kept up to date with the most recent patch release of each stream, such as
- Specific releases: Each specific release has an associated tag, such as
For a full list of tags, see Docker Hub: liquibase/liquibase.
liquibase:<version> image is considered the standard choice. If you're uncertain about your specific requirements, it's recommended to opt for this image. It is designed to serve as a disposable container as well as a foundational building block for creating other images.
liquibase:<version>-alpine image is a slimmed-down version of the Liquibase Docker container (
liquibase:<version>). It is designed to be lightweight and have a smaller footprint, making it suitable for environments with limited resources or when only the essential functionality is required. This image is built upon the popular Alpine Linux project, which can be found in the official Alpine image. Alpine Linux stands out for its significantly smaller size compared to other distribution base images, typically around 5MB. As a result, it enables the creation of overall slimmer images.
If your main concern is minimizing the final image size, this flavor proves to be quite useful. However, it is important to note that certain software may encounter issues depending on their specific
libc requirements or assumptions.
To keep the image size to a minimum, additional tools such as
bash are not commonly included in Alpine-based images. Instead, you can utilize this image as a foundation and add the necessary components in your own Dockerfile. For more information, see the "Create a custom image" section.
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>.
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 update --changelog-file=com/example/changelogs/root.changelog.xml
To generate a new changelog file at this location, run:
docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase generate-changelog --changelog-file=changelog/com/example/changelogs/root.changelog.xml
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
searchPath=/liquibase/changelog so that Liquibase can continue looking for your changelog files there.
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 --defaults-file=/liquibase/changelog/liquibase.properties update
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.
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
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:
Create a new container
FROM liquibase/liquibase RUN lpm add mysql --global
Then enter this command in the CLI:
docker build . -t liquibase/liquibase-mysql
For more information, see docker build.
Set environment variable at runtime
Alternatively, enter this command in the CLI:
docker run -e INSTALL_MYSQL=true liquibase/liquibase update
For more information, see Docker run reference § ENV (environment variables).
Specifying everything using arguments:
docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase/liquibase --license-key="<PASTE LB PRO 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>
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/liquibase --log-level=info update
Use the following example for configuring the
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 PRO LICENSE KEY HERE>
--defaults-file argument to evoke the
liquibase.docker.properties file when running commands in the CLI:
docker run --rm -v <PATH TO CHANGELOG DIR>:/liquibase/changelog liquibase/liquibase --defaults-file=/liquibase/changelog/liquibase.docker.properties update
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
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.
If you cannot use the default Liquibase Docker container image, you can create a custom image. You can either extend an existing Dockerfile or create a completely new image.
The best way to create a custom Docker image is to extend the Dockerfile to add whatever tools or drivers you want, such as a native executor. Then, publish your extended Dockerfile internally in your organization. For example, see /docker/examples, which contains both Alpine and non-Alpine Dockerfile examples.
FROM liquibase/liquibase RUN lpm add mssql --global
Then publish this custom Docker image internally.
To produce a new Liquibase Docker image, you must run a few Docker commands to inject the driver into the container. You can do this with any database. The following example is for a Microsoft SQL Server database running with the latest version of Liquibase:
- Download the latest Microsoft SQL Server driver, for example 12.2.0
- Start a Docker container:
docker run -it liquibase/liquibase:4.23.2 sh
- Do not exit out of this container. In a new terminal window, obtain the Container ID:
- Copy the Microsoft SQL Server 12.2.0 JAR file into the running container:
docker cp mssql-jdbc-12.2.0.jre11.jar <CONTAINER ID>:/liquibase/internal/lib
- Create a new Docker image:
docker commit <CONTAINER ID> liquibase/liquibase:4.23.2_w_mssql_12.2.0
- Publish this custom Docker image internally.
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: