Upgrade to Liquibase Secure with Docker

Last updated: September 18, 2025

Two distinct distributions of Liquibase Community and Liquibase Secure exist, and this differentiation provides a holistic setup experience that leads to purposeful releases and fewer regressions, built specifically for the workflow of our Secure users. It is important to know that the Secure distribution requires a valid license key to utilize all Community and Secure 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 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

1

Pull the Liquibase Docker image.

You can retrieve the image from Docker Hub by running the docker pull liquibase/liquibase-secure command.

2

Apply the Liquibase Secure 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

3

Verify the environment variable has been set.

Windows
echo $LIQUIBASE_LICENSE_KEY
Linux/macOS
echo %LIQUIBASE_LICENSE_KEY%

If the environment variable is set properly, the license key will display in the terminal.

4

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 run docker 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) or cd (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 and YOUR_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
docker run --rm
  -e LIQUIBASE_LICENSE_KEY=%LIQUIBASE_LICENSE_KEY%
  -v %cd%:/liquibase/changelog
  liquibase/liquibase
  --url="your_jdbc_url"
  --username=your_username
  --password=your_password
  --changelog-file=your-example-changelog.xml
  --search-path=/liquibase/changelog/
  update
Linux/macOS
docker run --rm \
  -e LIQUIBASE_LICENSE_KEY=$LIQUIBASE_LICENSE_KEY \
  -v "$(pwd)":/liquibase/changelog \
  liquibase/liquibase \
  --url="your_jdbc_url" \
  --username=liquibase \
  --password=password \
  --changelog-file=example-changelog.xml \
  --search-path=/liquibase/changelog/ \
  update

Results

A successful update message will appear if the Secure license key has been applied. This will include the expiration date for your license.

Sucessful Update Message
C:\Users\AmberWilliams>docker run --rm -e LIQUIBASE_LICENSE_KEY=%LIQUIBASE_LICENSE_KEY% -v %cd%:/liquibase/changelog liquibase/liquibase --url="jdbc:postgresql://host.docker.internal:5432/testdb" --username=postgres --password=liquibase --changelog-file=example-changelog.sql --search-path=/liquibase/changelog/ update
####################################################
##   _     _             _ _                      ##
##  | |   (_)           (_) |                     ##
##  | |    _  __ _ _   _ _| |__   __ _ ___  ___   ##
##  | |   | |/ _` | | | | | '_ \ / _` / __|/ _ \  ##
##  | |___| | (_| | |_| | | |_) | (_| \__ \  __/  ##
##  \_____/_|\__, |\__,_|_|_.__/ \__,_|___/\___|  ##
##              | |                               ##
##              |_|                               ##
##                                                ##
##  Get documentation at docs.liquibase.com       ##
##  Get certified courses at learn.liquibase.com  ##
##                                                ##
####################################################
Starting Liquibase at 23:11:35 using Java 17.0.14 (version 4.31.1 #6739 built at 2025-02-13 13:46+0000)
Liquibase Version: 5.0.0
Liquibase Secure 5.0.0 by Liquibase licensed to Liquibase until Tue Dec 12 00:00:00 UTC 2034
Database is up to date, no changesets to execute

UPDATE SUMMARY
Run:                           0
Previously run:                3
Filtered out:                  0
--------------------------------
Total change sets:             3

Secure Update Report created!
* File 'resourceaccessor:./Update-report-16-May-2025-182205.html' was created.
** To suppress Update reports add command arg 'liquibase update --report-enabled=false"
** To suppress all Secure Reports set liquibase.reports.enabled=false, or LIQUIBASE_REPORTS_ENABLED=false
# Liquibase command 'update' was executed successfully.

Tip: To check whether your Liquibase Secure 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 Secure license key is working correctly when passed into the container. It doesn't confirm whether the key has been saved or applied persistently.