Connect Liquibase MongoDB Secure with Amazon DocumentDB

If you're running Liquibase using the Maven plugin using mvn liquibase:update installing the extension with Maven ensures the right files are available and everything works together automatically. You can manage these extensions by adding them as dependencies in your project’s pom.xml file. When configured this way, Maven automatically downloads the specified JAR files from Maven Central during the build process.

1. Set the supportsValidator argument to false.

• Command line: --supports-validator=false

• liquibase.properties file: liquibase.mongodb.supportsValidator: false

• Environment variable: LIQUIBASE_MONGODB_SUPPORTS_VALIDATOR=false

2. Set the retryWrites argument to false.

• Command line: --retry-writes=false

• liquibase.properties file: liquibase.mongodb.retryWrites: false

• Environment variable: LIQUIBASE_MONGODB_RETRY_WRITES=false

• JDBC URL: &retryWrites=false. See the following section for examples of full URLs.

To use Liquibase with Amazon DocumentDB successfully, you must utilize the MongoDB Secure extension to create a connection between the two. If you want to use Amazon DocumentDB with TLS enabled, follow these instructions:

1. Follow the AWS instructions Connecting to an Amazon DocumentDB Cluster from Outside an Amazon VPC if needed to connect from outside an Amazon Virtual Private Cloud (VPC).

2. Create a Java Truststore. See Items 1 and 2 in Connecting Programmatically to Amazon DocumentDB § Connecting with TLS Enabled (Java snippet).

3. Add Amazon DocumentDB credentials. (liquibase.command.username, liquibase.command.password) to the liquibase.properties file, environment variables, or command line.

4. Specify the supportsValidator property.

liquibase.mongodb.supportsValidator: false

5. Specify a connection string. liquibase.command.url: mongodb://localhost:27017/my_dbname?directConnection=true&serverSelectionTimeoutMS=2000&tls=true&tlsAllowInvalidHostnames=true&retryWrites=false&tlsCAFile=PATH_TO_CAFILE/global-bundle.pem Note: The location localhost:27017 is used from the SSH tunnel (created on the first step) For connection from outside an Amazon VPC, it should contain attributes tls=true&tlsAllowInvalidHostnames=true&retryWrites=false&tlsCAFile=PATH_TO_CAFILE/rds-combined-ca-bundle.pem

6. Add information about Truststore to environment variables before running Liquibase commands.

On Linux: export JAVA_OPTS="-Djavax.net.ssl.trustStore=PATH_TO_TRUSTSTORE/rds-truststore.jks -Djavax.net.ssl.trustStorePassword=PASSWORD"

On Windows: set JAVA_OPTS="-Djavax.net.ssl.trustStore=PATH_TO_TRUSTSTORE\\rds-truststore.jks -Djavax.net.ssl.trustStorePassword=PASSWORD"

1. Ensure your Amazon DocumentDB database is configured.

For more information, see AWS Documentation: Get Started with Amazon DocumentDB.

2. Specify the database URL in the liquibase.properties file (defaults file), along with other properties you want to set default values for.

Liquibase does not parse the URL—you can either specify the full database connection string or specify the URL using your database's standard connection format.

TLS on: url: mongodb://localhost:27070/lbcat?tls=true&tlsAllowInvalidHostnames=true&retryWrites=false&tlsCAFile=rds-combined-ca-bundle.pem TLS off: url: mongodb://localhost:27069/lbcat?tls=false&retryWrites=false

Note: If you set retryWrites to false anywhere in your Liquibase project and to true elsewhere in your project—in the CLI, in your liquibase.properties file, as an environment variable, in the url argument, and so on—the value of false will always take priority, regardless of where you set it. To apply a Liquibase Secure key to your project, add the following property to the Liquibase properties file: licenseKey: <paste code here>

1. Create a text file called changelog (.sql, .yaml, .json, or .xml) in your project directory and add a changeset.

Native MongoDB Shell (mongosh) scripts in MongoDB Query Language (MQL): Let developers use Liquibase without modifying existing MQL scripts, which may be JavaScript (.js) files.

Formatted Mongo changelogs (MongoDB Secure 1.3.0+): Add Liquibase changeset metadata to your MQL scripts to use features like rollback, contexts, labels, and the include and includeAll tags. These must be saved as .js files.

YAML, JSON, and XML modeled changelogs: Specify changes for Liquibase to deploy without the need for MQL scripts. However, you can still deploy MQL scripts in YAML, JSON, and XML changelogs by using the mongo and mongoFile Change Types. Using these Change Types requires you to specify mongosh as the value of the runWith attribute for all mongo and mongoFile changesets.

Note for XML: The Liquibase MongoDB Secure extension uses a unique mongodb-secure XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

The preceding examples show only the mongo and mongoFile Change Types for Liquibase Secure. For a list of all Liquibase Secure and Liquibase Open Source Change Types for MongoDB, including Change Types that you can without the mongosh native executor, see Liquibase Change types for MongoDB.

2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

liquibase status --username=test --password=test --changelog-file=<changelog.xml>

Note: You can specify arguments in the CLI or keep them in the Liquibase properties file.

If your connection is successful, you'll see a message like this:

4 changesets have not been applied to <your_connection_url> Liquibase command 'status' was executed successfully.

3. Inspect the deployment SQL with the update-sql command

liquibase update-sql --changelog-file=<changelog.xml>

If the SQL that Liquibase generates isn't what you expect, you should review your changelog file and make any necessary adjustments.

4. Then execute these changes to your database with the update command:

liquibase update --changelog-file=<changelog.xml>

If your update is successful, Liquibase runs each changeset and displays a summary message ending with:

Liquibase: Update has been successful. Liquibase command 'update' was executed successfully.

5. From a database UI tool, ensure that your database contains the test_table object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.