Upgrade to Liquibase Pro 4.32 with Docker

In Liquibase 4.32 we provide two distinct distributions of Liquibase OSS and Liquibase Pro. This differentiation provides a holistic setup experience that leads to purposeful releases and fewer regressions specifically built 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.

Step-by-step

  1. Pull the Liquibase Docker image from Docker Hub into your setup by running the docker pull liquibase/liquibase command.

  2. Apply the Liquibase Pro license key in the CLI by first setting the key as an environment variable temporarily for the duration of the current terminal session. Once you close the terminal instance, this setting will be lost.

      Windows: set LIQUIBASE_LICENSE_KEY=<insert-license-key>
      Linux/MacOS: export LIQUIBASE_LICENSE_KEY=<insert-license-key>

    Tip: This example is for testing purposes, so It is best to use a Secrets Management tool like Hashicorp Vault or AWS Secrets Manager to keep Liquibase license keys secure.

  3. Ensure that the environment variable has been set by running the following command:
    4. Windows: echo $LIQUIBASE_LICENSE_KEY
    Linux/MacOS: echo %LIQUIBASE_LICENSE_KEY%
    When the environment variable is set properly, the license key will display in the terminal.
  4. Now run the following command to specify the license key as an environment variable. Ensure your database URL and changelog file is included in the update command.
    It's important to know that this command carries out all of these tasks:

    • Run the specified docker container.
    • Pass the Liquibase license key from your local environment into the container using the LIQUIBASE_LICENSE_KEY environment variable you set up in step 2.
    • Mount your current local directory into the container.

      • In the example code below, you are mounting the directory that you are currently in on your machine into the container and naming it /liquibase/changelog. Be sure to navigate to the directory that contains your changelog file before running the example code.

        Tip: You can check what directory you are in using ls.

        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 in order to update your changelog in the docker container at the path /liquibase/changelog.

    • Specify where the official Liquibase image is coming from Docker Hub.
    • Specify the JDBC URL connection for your database and map the host name in Docker to your local machine.
      • If you are working with a different Liquibase-supported database, visit the Liquibase Database Tutorials documentation to download the JDBC driver specific to your database.
    • Specify the user name and password credentials Liquibase needs to connect to the PostgreSQL database.
    • Specify the main changelog file that contains the list of Liquibase changesets.
    • Specify the search path for Docker to find the changelog inside the Docker image.
    • Run the update command to update the database.

    Before you run the example code, be sure to:

    • Navigate to the directory that contains your changelog in the CLI.
    • Update the 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

    • Windows:
      Copy
      Example code:
      docker run --rm
              -e LIQUIBASE_LICENSE_KEY=%LIQUIBASE_LICENSE_KEY%
              -v %cd%:/liquibase/changelog
              liquibase/liquibase
              --url="<i>your_jdbc_url</i>"
              --username=<i>your_username</i>
              --password=<i>your_password</i>
              --changelog-file=<i>your-example-changelog.xml</i>
              --search-path=/liquibase/changelog/
              update
    • Linux/MacOS:
      Copy
      Example code:
      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

    Optional: The Liquibase installation comes with JDBC drivers for popular database platforms such as Oracle, SQL Server, PostgreSQL, MariaDB, Snowflake, and H2.

  5. Once the command runs, notice in your log output that the latest version of Liquibase appears which confirms the license key is applied.
    Copy
    Successful log output example
    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: 4.31.1
    Liquibase Pro 4.31.1 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

    Pro 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 Pro Reports set liquibase.reports.enabled=false, or LIQUIBASE_REPORTS_ENABLED=false
    Liquibase command 'update' was executed successfully.
  6. You can also validate your Liquibase Pro license key in the CLI by running this command in your working directory:
    docker run --rm -e LIQUIBASE_LICENSE_KEY=<your-license-key> -it liquibase/liquibase:latest --version

Next steps