Reference S3 Files with Liquibase Commands

Note: Using Liquibase Pro with S3 is available in Liquibase Pro v4.17.0 and later.

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

search-path means the user-supplied search-path property via any standard configuration: the CLI, environment variables, liquibase.properties file, or the JAVA_OPTS Environment Variable. The search path locates files to read and is not used to write files. For more information, see How Liquibase Finds Files: Liquibase Search Path and Use --search-path with S3.

Use Absolute Paths with Remote Files in AWS S3

File(s)	Commands	Search-Path and Relative Path	Search-Path Only	Example
Generating a changelog (see below for calling a changelog in a command)	generate-changelog diff-changelog diff	--	--	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`	snapshot snapshot-reference	--	--	`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

File(s)	Commands	Absolute Path	Search-Path and Relative Path	Search-Path Only	Example
Using a changelog (changelog file/resources) SQL files include or includeAll files	update (all variants) rollback (all variants) changelog-sync status validate			--	`liquibase --search-path=s3://mybucket update --changelog-file=changelogs/changelog.xml` A relative changelog path is required to preserve the Liquibase tracking table integrity.

Using a changelog (changelog file/resources)

SQL files
include or includeAll files

update (all variants)
rollback (all variants)
changelog-sync
status
validate

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

File(s)	Commands	Absolute Path	Search-Path and Relative Path	Search-Path Only	Example
Snapshots (such as `mysnapshot.json`)	diff diff-changelog				`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`)	update (all variants) rollback (all variants)				`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.

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)

update (all variants)
rollback (all variants)

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.

Reference S3 Files with Liquibase Commands

Legend

Use Absolute Paths with Remote Files in AWS S3

Use Relative + Searchpath for changelogs in AWS S3

Use searchpath with remote files in AWS S3

Related videos

Learn more about Flow in Liquibase Pro

Learn how to use Flow files with s3