How Liquibase Finds Files: Liquibase Classpath

Liquibase finds the root changelog file and any referenced files by searching through the configured Liquibase classpath (also called a resource path).

Liquibase configures the classpath based on these factors:

  • The path specified in the classpath setting
  • Default locations based on how you run Liquibase
    • CLI: the current working directory where Liquibase commands are running
    • Maven: project’s classpath
    • Spring Boot: application’s classpath

Regardless of how you run Liquibase, it will need to find files, such as changelogs and jar files, and will search for them by appending all specified paths to root directories listed in the Liquibase classpath. For example, if you specify path/to/your/changelog.xml, Liquibase checks all configured directories in the classpath to find the requested file.

Setting your classpath

You can set the Liquibase classpath by choosing one of the following ways:

classpath in the liquibase.properties file

Add the following to your liquibase.properties file:

liquibase.classpath: path/to/your/resource/root

Note: If you use Liquibase versions prior to 4.4, follow this format: classpath: path/to/your/resource/root.

classpath as a CLI parameter

You can use classpath as a global parameter in your command line with a Liquibase command, such as update:

liquibase --classpath=path/to/your/resource/root update

Note: For more information about the CLI syntax, see the Command Line Interface documentation.

classpath as an environment variable

If you use Liquibase Pro, you can set classpath as an environment variable. The syntax for Mac/Linux:

LIQUIBASE_CLASSPATH=path/to/your/resource/root

The syntax for Windows, which requires the set command:

set LIQUIBASE_CLASSPATH=path/to/your/resource/root

Note: The CLI commands shown above only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the export command on Mac/Linux or the setx command on Windows.

Tip: If you use Maven, Ant, Spring Boot, or other integrations, you can set your classpath in the default files, such as pom.xml, application.yml, and others. Check the Tools & Integrations documentation for more.

How the Liquibase classpath worked before version 4.0

Before version 4.0, one of the default locations Liquibase added to the classpath was the root directory in your filesystem (/). The change caused issues because of a machine-dependent changelog path, such as /home/my-user/projects/liquibase/changelog.xml, found under the / directory. This way, Liquibase uses the given path as part of the changeset identifier stored in the DATABASECHANGELOG table, and when you run Liquibase from /home/other-user/projects/liquibase/changelog.xml, Liquibase sees it as a different changelog and tries to rerun all the previously run changesets.

To prevent identification issues from happening, a / was removed as a default part of the classpath.

How the Liquibase classpath works in 4.0 and later versions

Starting with Liquibase 4.0, the root directory (/) is no longer a default part of the classpath because of the issue mentioned in the previous section.

To migrate from your existing classpath format, including the root directory (/), to version 4.0+, you can do any of the following:

  • Configure your classpath to have a / as an additional location. The configuration brings back an old behavior with no file changes.
  • Add the logicalFilePath attribute to the root element of your changelog files. When you set the logicalFilePath value to be an old classpath version, Liquibase uses it for the comparison file name, which will match what is in the database. If you add the logicalFilePath, it will bring back the old behavior with file changes, and you will not have any runtime configuration changes.
  • Coordinate updates to the DATABASECHANGELOG table so that the filepath value gets changed to be a new path. You can do it with a single SQL statement, but the exact statement will depend on the database you use. See a PostgreSQL example:
  • Example: update databasechangelog set filepath=substring(filepath, length('/src/my-project')

You need to figure out the SQL statement and time when you run that statement because any passed existing references will start failing once you make the change, and any passed new references will fail until you do make the change.

Related links