• Task
  • Version ยท 5.2.2
  • Get started

Install Liquibase with Spring Boot

Last updated: August 7, 2026

The purpose of this tutorial is to guide you through the process of using Liquibase as part of your Spring Boot workflow.

The Liquibase Spring Boot integration ensures the application's database is updated along with the application code by embedding your changelog files in your application and automatically running Liquibase update as part of your application startup.

Before you begin

  • Ensure you have Java Development Kit (JDK 17+)

  • If you do not already have a Spring Boot application, you can create one with the Spring Initializer.

Procedure

1

Add the Liquibase dependency

If you did not already add the Liquibase dependency when creating your project, you can add it manually by adding com.liquibase:liquibase-secure-starter-all as a dependency to your project.

Be sure to replace your_version with the Liquibase version you want to download. For example, liquibase-secure-5.0.3.

loading

loading
2

Apply your Liquibase Secure license key

Using a Secrets Management tool like Hashicorp Vault or AWS Secrets Manager is best to keep Liquibase license keys secure.

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

Include the Liquibase Secure license key in the Liquibase properties file and save it.

For example:

liquibase.licenseKey: aei76ou32thp785463214

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

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

For example:

liquibase --license-key=aei76ou32thp785463214 update

Set the Liquibase Secure 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 Secure license key with the JAVA_OPTS Environment Variable in the command line:

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

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-secure:latest sh

If you use Maven, include the Liquibase Secure license key in the <properties> section of your pom.xml file:

<liquibaseLicenseKey>key-goes-here</liquibaseLicenseKey/>

For example:

<plugin> <groupId>org.liquibase</groupId> <artifactId>liquibase-commercial-maven-plugin</artifactId> <version>0-SNAPSHOT</version> <configuration> <changelogFile>com/example/changelog_v4.6.xml</changelogFile> <liquibaseLicenseKey>key-goes-here</liquibaseLicenseKey> </configuration> </plugin>

Note: In older versions of Liquibase, you must use the syntax <liquibaseProLicenseKey> instead of <liquibaseLicenseKey>.

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 Secure 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: <dependency> <groupId>org.liquibase</groupId> <artifactId>liquibase-commercial</artifactId> <version>4.33.0</version> </dependency>

  2. In your custom Java file, import the following: 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 Secure update-one-changeset command: 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.

3

Add a Changelog File

Create a changelog file in your project. By default, The Spring Boot Liquibase integration looks for a file named db.changelog-master.xml in the src/main/resources/db/changelog directory.

loading
4

Start your application

When you start your application with mvn spring-boot:run or gradle bootRun, Liquibase will automatically run the changelog file and update your database.

Try it now, and you should see the table test_table created in your database.

PreviousInstall Liquibase on Red Hat or CentOSNextInstall Liquibase on Windows