Detailed Guidelines for Referencing S3 Files with Liquibase CLI Commands

Correct configuration of paths to locate files is vital to using Liquibase files stored in S3. The following tables provide high-level guidance to read or write remote Liquibase files.

Note: An output of log files to S3 is not yet available.

Legend

  • searchpath means the user-supplied searchpath property via any standard configuration, i.e., CLI, environment variables, liquibase.properties file, or the JAVA_OPTS Environment Variable. The searchpath locates files to read. Searchpath is not used to write files.

Use Absolute Paths with Remote Files in AWS S3

File(s) Commands Absolute Path Search-Path and Relative Path Search-Path Only Example
Generating a changelog (see below for calling a changelog in a command)     Relative changelog path required to preserve DBCL integrity.
flowfile (such as liquibase flowfile.yaml) flow    
liquibase flow --flow-file s3://mybucket/liquibase.flowfile.yaml
  • If the flow file references changelogs, the search-path must be configured. Within the flow file, the path to the changelog should be relative to the search-path.
  • If the flow file references a checks settings file, provide an absolute path in the flow file.
  • If a flow file calls the flow command internally, provide an absolute path to the referenced flow file.
Checks settings file (such as liquibase.checks-settings.conf) checks (all subcommands)    
liquibase checks run --checks-settings-file s3://mybucket/liquibase.checks-settings.conf
Defaults file (such as liquibase.properties) All    
liquibase --defaults-file s3://mybucket/defaults/liquibase.properties history
init project files
  • changelog
  • flow file
  • liquibase.properties
init project    
liquibase init project --project-dir s3://mybucket//init --project-guide off --changelog-file example-changelog.postgres.sql

The changelog-file attribute cannot be relative when passed to init project in the --changelog-file parameter. This is the only use case where changelog-file is not relative.

output-files All commands which support the --output-file property.    
liquibase --output-file s3://mybucket/snapshots/mysnap.json snapshot
driver.properties All that support the driver-properties property.    
liquibase --search-path s3://myS3Bucket/properties/drivers update --driver-properties mydriver.properties
snapshot.json    
liquibase --output-file s3://mybucket/snapshots/mysnap.json snapshot

Use Relative + Searchpath for changelogs in AWS S3

File(s) Commands Absolute Path Search-Path and Relative Path Search-Path Only Example
Using a changelog (changelog file/resources)    
liquibase --search-path s3://mybucket update --changelog-file changelogs/changelog.xml

A relative changelog path is required to preserve the Liquibase tracking table integrity.

Use searchpath with remote files in AWS S3

File(s) Commands Absolute Path Search-Path and Relative Path Search-Path Only Example
Snapshots (such as mysnapshot.json)    
liquibase --search-path s3://mybucket/mysnapshots diff --reference-url offline:postgres?snapshot=mysnapshot.json
Native executor config files (such as liquibase.sqlplus.conf, liquibase.sqlcmd.conf, liquibase.psql.conf)    
liquibase --search-path s3://mybucket/configs update

There is no property to directly specify a native executor configuration file path. It is located using the searchpath property.