Connect Liquibase to Amazon S3

Last updated: July 14, 2025

This feature is available in Liquibase Pro v4.17.0 and later.

Starting with Liquibase Pro 4.31.0, new features and fixes are not applied to the individual AWS S3, AWS Secrets Manager, and Amazon DynamoDB Pro extensions. While you can still use the individual extensions, it will not receive future updates. We recommend using the Liquibase AWS extension to get the latest improvements and prevent conflicts.

Liquibase integrates the use of Amazon S3 to store and retrieve data from anywhere. Extending Liquibase to use remote file locations enables secure, centralized file management. Liquibase files include changelogs, snapshots, SQL files, liquibase.properties files, native executor configuration files, checks settings configuration files, and flow files. Remote file location access allows you to build a reusable repository of Liquibase files. It also removes the need for all developers to have local copies of Liquibase files, which ensures files are always accurate.

Note: By default, S3 enforces TLS, which ensures that secrets are safe while in transit. Learn more here: Enforcing encryption with Amazon S3.

Procedure

1

Download liquibase-AWS-extension-<version>.jar and put it in the liquibase/lib directory.

If you use Maven, add this dependency to your pom.xml file:

<dependency> <groupId>org.liquibase</groupId> <artifactId>liquibase-AWS-extension</artifactId> <version>1.1.3</version> </dependency>

2

Configure your AWS keys as local environment variables or in your AWS configuration files. You can use these secure credentials instead of a traditional username and password.

You must set the following keys:

  • AWS_REGION

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN (optional)

For example, if you use AWS configuration files, you can set this in your config file (~/.aws/config):

[default] region=us-east-2

In your shared credentials file (~/.aws/credentials), you can use temporary values from your AWS access portal. For example:

[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

3

Optional: If you usually store your Liquibase Pro license key in a defaults file which you want to store on S3, set up your license in an environment variable, in the CLI, or with another standard property-setting method and then export the key in the CLI.

  1. For more information about environment variables, see our article on environment variables.

  2. A. Add the Liquibase license key to the environment variable.

  3. LIQUIBASE_LICENSE_KEY=Enter Key Here

  4. B. Export the key in the CLI.

  5. For Linux or MacOS, use this syntax. For Windows command prompt or PowerShell, use the syntax described in the Amazon article Configuring environment variables for the AWS CLI.

  6. Export LIQUIBASE_LICENSE_KEY="Enter Key Here"

  7. A Liquibase Pro license key is needed to access remote S3 files. Therefore, the license key will not be accessible if only stored in a remote S3 defaults file. It is best practice to set up an environment variable that contains the key.

  8. Once the AWS keys and Liquibase Pro license key are configured, you are ready to begin using S3 with Liquibase.

Connect Liquibase to Amazon S3 - Liquibase