How does Liquibase find files?

JAR files are packages of aggregated Java class files and associated metadata built on a ZIP format, which contains application functionality. In order to use the functionality of the JAR file, Liquibase needs to find the JAR file.

In addition to JAR files, Liquibase also needs to find the changelog and looks for both of these file types in the following locations:

• Any paths specified in the classpath setting.

• Note: Liquibase uses the classpath to find all JARs in any location you specify, except for extension JARs, such as the Liquibase extension for DynamoDB. Extension JARs included via classpath must go in one of the following locations: ./liquibase_libs, lib, internal/lib, or internal/extensions.

• The current working directory.

• A liquibase_libs directory in the current working directory.

• A lib directory in the Liquibase install location.

• Inside any .zip or .jar files in the liquibase_libs or lib directories.

• Using --search-path (v4.13 and later). For more information about --search-path

  , continue reading this page.

We recommend that you add .jar files to the $LIQUIBASE_HOME/lib folder.

Tip: $LIQUIBASE_HOME is an environment variable that points to the location of the directory where Liquibase is installed on your machine. You can set environment variables using your operating system's shell. The location of $LIQUIBASE_HOME will depend on where Liquibase was installed on your machine.

Liquibase uses the paths to files as part of changeset identifiers. It is important for these paths to remain consistent and stable, because they are often included in shared changelog files, even when the physical location of those files may change from machine to machine.

To provide that separation between the file reference and the file's physical location, Liquibase uses the concept of a "search path." The search path is the list of base physical locations where given changelog paths can be found. Liquibase will check all those locations for each file to look up.

For example, if your referenced file path is db.changelog.xml and your search path is /Users/example/liquibase,/projects/global, Liquibase will look for /Users/example/liquibase/db.changelog.xml and /projects/global/db.changelog.xml.

For example, if your referenced file path is project1/db.changelog.xml and your search path is /Users/example/liquibase,/projects/global, Liquibase will look for /Users/example/liquibase/project1/db.changelog.xml and /projects/global/project1/db.changelog.xml.

It does not matter if your referenced file path starts with a / or not, Liquibase always looks up the file path within your search path.

Liquibase configures the search path based on these factors:

• The path specified in the --search-path setting

• Default locations based on how you run Liquibase

  • CLI: the current working directory where Liquibase commands are running, plus everything in your LIQUIBASE_HOME/lib and liquibase_libs directories, plus the classpath setting

  • Maven: project’s classpath

  • Spring Boot: application’s classpath

  Note: When --search-path is set, Liquibase will only search along that path and it overrides the default settings.

Syntax

You can set this parameter in the following ways:

For more information, see Working with Command Parameters.

Tip: If you use Maven, Ant, Spring Boot, or other integrations, you can set your searchPath in the default files, such as pom.xml, application.yml, and others.