How Liquibase Finds Files: Liquibase Search Path

Regardless of how you run Liquibase, it needs to find your changelogs. Because Liquibase uses the paths to files as part of the change set identifiers and because paths are often included in shared changelog files, it is important for those stored paths to remain consistent and stable, even when the physical location of those files may change from machine to machine.

To provide that separation between the file reference and the physical location of the file, 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, and for each file to look up, Liquibase will check all those locations for the file.

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 searchPath 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

Setting your search path

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

searchPath in the Liquibase properties file

Add the following to the Liquibase properties file:

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

searchPath as a CLI parameter

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

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

Note: For more information about the CLI syntax, see the Working with Command Parameters documentation.

searchPath as an environment variable

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

LIQUIBASE_SEARCH_PATH=path/to/your/resource/root

The syntax for Windows, which requires the set command:

set LIQUIBASE_SEARCH_PATH=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 searchPath in the default files, such as pom.xml, application.yml, and others. Check the Tools & Integrations documentation for more.

How the Liquibase search path worked before version 4.13

Before version 4.13, the search path was not configured separately from the classpath. The logic of always looking up file references via a set of base locations was the same, but the only way to configure those locations was through the classpath configuration.

Before version 4.0, one of the default locations Liquibase added to the searchPath/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 searchPath/classpath.

How the Liquibase searchPath works in 4.0 and later versions

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

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

  • Configure your searchPath to include /. 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 file reference name, 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