How does Liquibase handle file paths?

Applies to: 

• Liquibase Secure (Pro)
• Liquibase Community (Open Source)

Question:

How does Liquibase handle file paths either set in the CLI command or in the liquibase.properties file?

Answer:

There are two styles of file paths used, Windows and Linux. 

• Windows-style file paths will use the backslash, "\", character to specify directories
  • Example: C:\Users\Administrator\Liquibase\liquibase.properties
• Linux-style file paths will use the forward slash, "/", character to specify directories
  • Example: /c/Users/Administrator/Liquibase/liquibase.properties

Both styles can be used in a Liquibase project. However, it depends on where the path is used which determines which version will be accepted.

Command Line Interface (CLI)

When Liquibase runs, the paths provided via CLI arguments are handled by the shell being used. When setting a file path on the CLI, it needs to be in the style that is accepted by the shell in use. 

For example, if there is a Windows computer that has both Powershell and Git Bash installed, the path style will need to match the shell in use.

• Powershell (Windows-based)

  • liquibase --defaults-file=C:\Users\Administrator\liquibase_project\liquibase.properties status

• Git Bash (Linux-based)

  • liquibase --defaults-file=/c/Users/Administrator/liquibase_project/liquibase.properties status

liquibase.properties file

The paths inside the liquibase.properties file are processed via the Java Virtual Machine (JVM). Either the Windows or Linux pathing structure can be used and the JVM will convert the pathing to work for that operating system.

Changelogs

Regardless of the development environment, always use forward slashes / in your changelog files for file paths, for example:

databaseChangeLog:
 - include:
     file: 2025/02/28-changelog.yaml

Relative Paths

Use relative paths instead of absolute paths. This approach ensures that your changelog files remain portable across different environments. The relativeToChangelogFile attribute helps maintain consistency:

databaseChangeLog:
 - include:
     file: 2025/02/28-changelog.yaml
     relativeToChangelogFile: true

Related Article(s):

How Liquibase Finds Files: Liquibase Search Path