Liquibase Relative Path Best Practices
Liquibase 4.0 and later doesn’t allow specifying absolute paths because the absolute path might cause issues with deployment, identification of your changelog file, and others from which it is difficult to recover. Instead, use paths relative directories included in your
Liquibase uses the path to the changelog file as part of the changeset identifier. A file specified by the path
com/example/cart/changelog.xml is different from those that are specified by the
Similarly, a path like
/src/my-project/com/example/changelog.xml is different from
/src/renamed-project/com/example/changelog.xml. It is common for the absolute path of your project to change over time on your machine or to be different on different machines. When that absolute path changes, Liquibase determines those paths as different, and thus, the changesets become different as well. So, you might need to run the changesets again.
Using the relative path with Liquibase files
Liquibase checks for files relative to the directories configured in the
classpath, so as long as
com/example/changelog.xml is in a directory included in the classpath, Liquibase will find it. The locations in the
classpath can be changed from
/src/my-project to /src/renamed-project,
/home/my-user/my-project/, or others, and Liquibase will continue seeing the changelog as
classpath can be configured varies depending on how you run Liquibase:
- If you use the CLI, the
classpathrepresents your current working directory and anything included in the
- If you use Maven, the
classpathis your project's
- If you use Spring Boot, the
classpathis your application's
However, regardless of the way you run Liquibase, there is a set of directories, .jar files, and .zip files Liquibase checks.
Migrating from absolute paths
The relative path syntax for Windows and Unix is the same. For example:
../changelog.xml. To change your existing absolute path to a relative path, you can do any of the following:
- Configure your
classpathto have a
/as an additional location. The configuration brings back the old behavior with no file changes, and as a result, you will have only runtime configuration changes.
- Add the
logicalFilePathattribute to the root element of your changelog files. When you set the
logicalFilePathvalue to be the old absolute path, 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
filepathvalue gets changed to be a non-absolute 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 absolute references will start failing once you make the change, and any passed relative references will fail until you do make the change.