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 needs to find your changelogs and JAR files. It searches 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 the Liquibase properties file:
Note: If you use Liquibase versions prior to 4.4, follow this format:
classpath as a CLI parameter
You can use
classpath as a global parameter in your command line with a Liquibase command, such as
liquibase --classpath=path/to/your/resource/root update
Note: For more information about the CLI syntax, see the Working with Command Parameters documentation.
classpath as an environment variable
If you use Liquibase Pro, you can set
classpath as an environment variable. The syntax for Mac/Linux:
The syntax for Windows, which requires the
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
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
logical-file-pathattribute to the root element of your changelog files. When you set the
logical-file-pathvalue 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
logical-file-path, 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:
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.