Upgrade to Liquibase Pro with Docker
Last updated: September 18, 2025
Two distinct distributions of Liquibase OSS and Liquibase Pro exist, and this differentiation provides a holistic setup experience that leads to purposeful releases and fewer regressions, built specifically for the workflow of our Pro users. It is important to know that the Pro distribution requires a valid license key to utilize all OSS and PRO features. You can run a Docker container in many ways. Please use the tools aligned with your company's workflow, such as AWS ECS or GitHub Actions, or other container orchestration platforms.
Before you begin
Confirm your machine meets the system requirements.
Confirm your
liquibase.properties
file is available in your Liquibase directory.Ensure the Docker daemon is running:
Windows and MacOS: Docker daemon starts automatically when you open Docker Desktop.
Linux: Run the sudo systemctl start docker
command to start the Docker service.
Ensure that your database is accessible from the Docker container. If the database is running outside of Docker, confirm that you have network access. This can be done by running
host.docker.internal
on Windows or macOS.
Procedure
Pull the Liquibase Docker image.
You can retrieve the image from Docker Hub by running the docker pull liquibase/liquibase
command.
Apply the Liquibase Pro license key in the CLI.
Pass the Liquibase Secure license key while using a Docker container. Docker allows the use of--env
in the command.
docker run --env LIQUIBASE_LICENSE_KEY=<enter license key here>... \
-it liquibase/liquibase:latest sh
Tip: To check whether your Liquibase Pro license key is working, run the following command from your working directory:
docker run --rm -e LIQUIBASE_LICENSE_KEY=
<your-license-key>
-it liquibase/liquibase:latest --version
This command verifies that your Liquibase Pro license key is working correctly when passed into the container. It doesn't confirm whether the key has been saved or applied persistently.
Verify the environment variable has been set.
Windows
Linux/macOS
The license key will display in the terminal if the environment variable is set properly.
Use the docker run command to apply your changes.
Now you'll run the docker run
command to update your database using Liquibase inside a Docker container.
This command does the following:
Starts the official Liquibase Docker container.
Passes your Liquibase license key into the container via the
LIQUIBASE_LICENSE_KEY
environment variable.Mounts your current working directory into the container at
/liquibase/changelog
. Note: You may need to give Docker permission to access the directory you want to mount into the container. Mounting the directory allows you to make changes to your changelog, save the file, and rundocker run
to update your changelog in the Docker container at the path /liquibase/changelog.Connects to your database using the JDBC URL, username, and password you provide. Note: The Liquibase Docker image includes JDBC drivers for popular databases like PostgreSQL, Oracle, SQL Server, MariaDB, Snowflake, and H2. If you're using a different database, download the appropriate JDBC driver and follow the instructions in the Liquibase Database Tutorials.
Executes the
update
command using the changelog file in your mounted directory.
Before you run the example code, be sure to:
Navigate to the directory that contains your changelog in the CLI. Tip: Use
pwd
(Mac/Linux) orcd
(Windows) to check your current directory.Update
YOUR_JDBC_URL
with your JDBC URL. For example:jdbc:postgresql://host.docker.internal:5432/testdb
Update
YOUR_USERNAME
andYOUR_PASSWORD
with your credentials for your database.Update
YOUR_CHANGELOG_FILE
with the name of the changelog file on your local machine. For example:your-example-changelog.xml
Note: Docker may prompt you to grant access to the directory you're mounting.
Windows
Linux/macOS
Results
A successful update message will appear if the Secure license key has been applied. This will include the expiration date for your license.