Liquibase Relative Path Best Practices

Tip: Specifying files by absolute path was removed in Liquibase 4.0. Please use a relative path or add '/' to the classpath parameter.

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 classpath.

Uses

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 com/example/account/changelog.xml, com/example/changelog.xml, or changelog.xml path.

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 com/example/changelog.xml.

How the classpath can be configured varies depending on how you run Liquibase:

  • If you use the CLI, the classpath represents your current working directory and anything included in the classpath setting.
  • If you use Maven, the classpath is your project's classpath.
  • If you use Spring Boot, the classpath is your application's classpath.

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 classpath to 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 logicalFilePath attribute to the root element of your changelog files. When you set the logicalFilePath value 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 filepath value 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:
  • 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.