Upgrade to Liquibase Pro 4.32

In Liquibase 4.32 we provide two distinct distributions of Liquibase OSS and Liquibase Pro.This differentiation provides a holistic setup experience that supports purposeful releases and reduces the risk of regressions. This experience is specifically tailored to the workflows 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.

Prerequisites

Step-by-step

  1. Navigate to your preferred Liquibase installer:

    • For Liquibase Pro users, you have the option to use our new Pro-only installer. This version requires a paid Liquibase license key.

    • For Liquibase OSS users, or Pro users who are not ready to move to our Pro-only distribution, use our Liquibase OSS installer.

  2. Extract it to the location of your choosing.
    Example:

    • On Linux, extract the zip file into /opt/liquibase/liquibase-<version> directory.

    • On Windows, extract the zip file into the C:\liquibase\liquibase-<version> directory.

    • On MacOS, extract the zip file into ~/liquibase/liquibase-<version> directory.

  3. Run the CLI as an Administrator.

    Note: The Symbolic link will not work unless you are in Administrator mode.

  4. Navigate to the location of the new Liquibase download.

  5. Create a symbolic link to Liquibase.

    Symbolic links allow DevOps engineers to control which version of Liquibase executes upon install. This method allows the pipeline maintainer to link a specific version of Liquibase, which has been tested and vetted by the DevOps engineer prior to using it widely on the dev environment.

    • Linux:
      On one end of this link we have the liquibase-<version> component where the DevOps engineer will place the latest version of Liquibase. On the other end we have the DBAs with the ./liquibase component that looks at the DevOps's end and finds the latest version. So, once the DevOps Engineer is ready for the DBAs to release this to the development environment they can just create this symbolic link and the DBAs automatically get the latest version.

      In this example we will use /opt/liquibase/liquibase to link to the /opt/liquibase/liquibase-<version> ./liquibase by entering the below command in the CLI:

      sudo ln -sf ./liquibase-version> ./liquibase

    • Windows:  

      On one end of this link we have the liquibase-<version> component where the DevOps engineer will place the latest version of Liquibase. On the other end we have the DBAs with the C:\liquibase\liquibase component that looks at the DevOps's end and finds the latest version. So, once the DevOps Engineer is ready for the DBAs to release this to the development environment they can just create this symbolic link and the DBAs automatically get the latest version.

      In this example we will use C:\liquibase\liquibase to link to the C:\opt\liquibase\liquibase-<version> directory by entering the below command in the CLI:

      mklink/d C:\liquibase\liquibase C:\liquibase\liquibase-<version>

  6. Update the environment variable so it points to the Liquibase symbolic link just created by entering this into the CLI:

    • Linux: If Liquibase is installed in /opt/liquibase/liquibase-4.29.2 with a symbolic link created at /opt/liquibase/liquibase, then run this in the CLI:

      export PATH=/opt/liquibase/liquibase:$PATH

    • Windows:  If Liquibase is installed in C:\liquibase\liquibase-4.29.2 with a symbolic link created at C:\liquibase\liquibase, then run this in the CLI:

      SET PATH=C:\liquibase\liquibase;%PATH%

  7. Open another instance of the CLI to load the new changes.

  8. Ensure that the liquibase.properties file is available in your liquibase-4.32 directory. As an existing user, copy your existing properties file and paste it into your 4.32 directory folder.

    In this example, you can see the liquibase.properties in the main liquibase-4.32 directory.

  9. To be able to run a database update, ensure that your changelog is available in your liquibase-4.32 directory. As an existing user, copy your existing changelog file and paste it into your 4.32 directory folder.
    In this example, you can see the example-changelog.sql file in the main liquibase-4.32 directory.

  10. Apply your Liquibase Pro license key in any of the below methods you prefer.

    Tip: It is best to use a Secrets Management tool like Hashicorp Vault or AWS Secrets Manager to keep Liquibase license keys secure.

    There are several ways to apply the Liquibase Pro license key:

    Include the Liquibase Pro license key in the Liquibase properties file and save it. For example:

    liquibase.licenseKey: aei76ou32thp785463214

    Pass the Liquibase Pro license key as a parameter in the command line during runtime:

    liquibase --license-key=[paste the Liquibase Pro license key] [command]

    For example:

    liquibase --license-key=aei76ou32thp785463214 update

    Set the Liquibase Pro license key as an environment variable in the command line.

    On Windows:

    set LIQUIBASE_LICENSE_KEY=aei76ou32thp785463214

    On Linux/macOS:

    export LIQUIBASE_LICENSE_KEY=aei76ou32thp785463214

    Set the Liquibase Pro license key with the JAVA_OPTS Environment Variable in the command line:

    JAVA_OPTS="Dliquibase.licenseKey=<enter license key here>"

    Pass the Liquibase Pro 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

    If you use Azure DevOps and pass your license key as an environment variable, you can set the value of LIQUIBASE_LICENSE_KEY in your Azure DevOps pipeline setting file:

    script: |
    echo "Running Policy Checks"
    liquibase checks run --changeLogFile=mysqlChangelog.xml
displayName: 'Run Policy Checks'
env:
    LIQUIBASE_LICENSE_KEY: $(LiquibaseKey)

    In this example, LiquibaseKey is the name of the Azure DevOps project variable whose value is the license key.

    You can directly embed your Liquibase Pro license key (myProLicenseKey) in a custom Java application by following these steps:

    1. In your Maven pom.xml file, point to liquibase-commercial.jar as a dependency:
      2. <dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-commercial</artifactId>
    <version>4.33.0</version>
</dependency>
    2. In your custom Java file, import the following:
      3. import com.datical.liquibase.ext.config.LiquibaseLabsConfiguration;
    3. In your custom Java file, call on the LiquibaseLabsConfiguration class. For example, to specify your license key so that you can run the Liquibase Pro update-one-changeset command:
      4. Scope.child(LiquibaseLabsConfiguration.LICENSE_KEY.getKey(), "myProLicenseKey", () ->
    new CommandScope(UpdateOneChangeSetSqlCommandStep.COMMAND_NAME)
        .addArgumentValue(DbUrlConnectionArgumentsCommandStep.DATABASE_ARG, liquibase.getDatabase())
        .addArgumentValue(DatabaseChangelogCommandStep.CHANGELOG_FILE_ARG, "/db_schema/changelog.xml")
        .addArgumentValue(UpdateOneChangeSetCommandStep.CHANGESET_AUTHOR_ARG, "fl")
        .addArgumentValue(UpdateOneChangeSetCommandStep.CHANGESET_ID_ARG, "1")
        .addArgumentValue(UpdateOneChangeSetCommandStep.CHANGESET_PATH_ARG, "/db_schema/changelog.xml")
        .execute()
);

    For information on running Liquibase commands in Java files, see liquibase.command.CommandScope.

  11. Optional: The Liquibase installation comes with JDBC drivers for popular database platforms such as Oracle, SQL Server, PostgreSQL, MariaDB, Snowflake, and H2.
    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.

  12. In a new CLI instance, navigate to the location you just downloaded the Liquibase Pro distribution to.

  13. Validate that your Liquibase Pro license key works as expected and check its expiration date by running the liquibase update command.
    Confirm that a message like this appears:

    Copy

    Successful Update Message

    For more information, please use the --log-level flag

    C:\Users\AmberWilliams\Projects\liquibase-4.32>liquibase update
    ####################################################
    ##   _     _             _ _                      ##
    ##  | |   (_)           (_) |                     ##
    ##  | |    _  __ _ _   _ _| |__   __ _ ___  ___   ##
    ##  | |   | |/ _` | | | | | '_ \ / _` / __|/ _ \  ##
    ##  | |___| | (_| | |_| | | |_) | (_| \__ \  __/  ##
    ##  \_____/_|\__, |\__,_|_|_.__/ \__,_|___/\___|  ##
    ##              | |                               ##
    ##              |_|                               ##
    ##                                                ##
    ##  Get documentation at docs.liquibase.com       ##
    ##  Get certified courses at learn.liquibase.com  ##
    ##                                                ##
    ####################################################
    Starting Liquibase at 16:10:55 using Java 21.0.1 (version merge-test #12 built at 2025-04-28 21:24+0000)
    Liquibase Version: 4.32
    Liquibase Pro 4.32 by Liquibase licensed to Liquibase until Mon Dec 11 17:00:00 MST 2034
    Running Changeset: example-changelog.sql::1::your.name
    Running Changeset: example-changelog.sql::2::your.name
    Running Changeset: example-changelog.sql::3::other.dev

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

    Liquibase: Update has been successful. Rows affected: 3
    Pro Update Report created!
    * File '/C:/Users/AmberWilliams/Projects/liquibase-4.32/Update-report-01-May-2025-161057.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.

    C:\Users\AmberWilliams\Projects\liquibase-4.32>