What are the rules for using search-path with remote files?

Rules

Below are all of the rules that apply to --search-path. Review the example use cases and instructions to ensure it is the right avenue for your project.

Multiple searchpaths

If search-path is set, it is used, and Liquibase will not look in other locations for changelog or snapshot files. Therefore, if some necessary files are located in remote storage and some are local, both locations are required in the search path.

• When not specifically configured, by default --search-path looks for changelogs in the current working directory.

• When --search-path is configured, only the locations explicitly defined in --search-path are used to locate changelogs.

• Multiple --search-path locations are comma-separated and processed in order.

S3 example: --search-path=s3://myBucket/demo,C:\Users\Me\demo Azure example:

--search-path=az://myContainer/demo,C:\Users\Me\demo

• If multiple --search-path locations are specified, Liquibase may find two or more changelog files with the same name. To determine how Liquibase behaves in this case, see the "Duplicate File Mode" section of this document.

Note: If the changelog references resource files in multiple directories, it may be easier to define the --search-path as an environment variable. This prevents the --search-path property from making the command line unreadable. The --search-path environment variable is LIQUIBASE_SEARCH_PATH.

Multiple --search-path locations example:

--search-path=s3://myBucket/path,.localfiles

Note: s3://myBucket/path is the first location and .localfiles is the second location that search-path will find the files.

Duplicate File Mode

The --duplicate-file-mode property determines how Liquibase behaves when multiple changelogs are found in the multiple locations specified in the --search-path property. By default, an ERROR will be thrown to halt execution, but --duplicate-file-mode can be set to SILENT, DEBUG, INFO, or WARN instead, settings which log the issue but do not halt execution. In these cases, it uses the first changelog file found in a sequential processing of --search-path locations.

Error Response

The ERROR response states two files are found and Liquibase will not use either file. It will then suggest you rename the file or correct the value you specify for --search-path, and then re-run the command.

Example: Default behavior of --duplicate-file-mode when changelog.xml is located in two --search-path directories.

In this example, a changelog named changelog.xml is located in both s3://myBucket/demo and in s3://myBucket/demo2.

liquibase --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml

Liquibase console output shows an error and does not execute the update-sql command.

Unexpected error running Liquibase: Error changelog.xml   - Caused by: Found 2 files with the path 'changelog.xml':     - s3://myS3Bucket/demo/changelog.xml     - s3://myS3Bucket/demo2/changelog.xml   Search Path:     - s3://myS3Bucket/demo/changelog.xml     - s3://myS3Bucket/demo2/changelog.xml   You can limit the search path to remove duplicates with the liquibase.searchPath setting. Or, if you KNOW these are the exact same file you can set liquibase.duplicateFileMode=WARN.

liquibase --duplicate-file-mode=ERROR --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml results in update-sql exiting with an ERROR that duplicate changelog.xml file was located.

Example: Behavior when --duplicate-file-mode set to ERROR and changelog.xml is located in two search-path directories

Although the default for --duplicate-file-mode is ERROR, you can explicitly configure the setting to throw an error. In this example, a changelog named changelog.xml is located in both s3://myBucket/demo and in s3://myBucket/demo2.

liquibase --duplicate-file-mode=ERROR --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml

Liquibase console output shows an error and does not execute the update-sql command.

Unexpected error running Liquibase: Error changelog.xml   - Caused by: Found 2 files with the path 'changelog.xml':     - s3://myS3Bucket/demo/changelog.xml     - s3://myS3Bucket/demo2/changelog.xml   Search Path:     - s3://myS3Bucket/demo/changelog.xml     - s3://myS3Bucket/demo2/changelog.xml   You can limit the search path to remove duplicates with the liquibase.searchPath setting. Or, if you KNOW these are the exact same file you can set liquibase.duplicateFileMode=WARN.

Warn response

The WARN response states two files are found and it will automatically use the first file found.

Example: Behavior when --duplicate-file-mode set to WARN and changelog.xml is located in two --search-path directories.

To explicitly ignore duplicate changelogs in the searchpath, configure --duplicate-file-mode to WARN. In this example, a changelog named changelog.xml is located in both s3://myBucket/demo and in s3://myBucket/demo2.

liquibase --duplicate-file-mode=WARN --search-path=s3://myBucket/demo,s3://myBucket/demo2 update-sql --changelog-file=changelog.xml

Liquibase console output shows a warning. The update-sql command is executed using the changelog in s3://myBucket/demo.

Found 2 files with the path 'changelog.xml': - s3://myS3Bucket/demo/changelog.xml - s3://myS3Bucket/demo2/changelog.xml Search Path: - s3://myS3Bucket/demo/changelog.xml - s3://myS3Bucket/demo2/changelog.xml You can limit the search path to remove duplicates with the liquibase.searchPath setting. To fail when duplicates are found, set liquibase.duplicateFileMode=ERROR Choosing: s3://myS3Bucket/demo/changelog.xml