You do not need to install drivers if you are using the Liquibase MongoDB Pro extension. You will need to place the liquibase-commercial-mongodb-<version>. jar file in the $LIQUIBASE_HOME/lib directory. Use the buttons above to navigate to the required downloads and extract them to your Liquibase /lib folder.

Note: Do not specify a driver in the liquibase.properties file.

If you prefer, you can use environment variables to point to the directory where Liquibase is installed on your machine. You can set environment variables using your operating system's shell. The location of $LIQUIBASE_HOME will depend on where Liquibase was installed on your machine.

Note for Maven users: 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. Configuring Maven this way ensures that the necessary JAR files are retrieved from Maven Central during the build phase.

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 Pro 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. Tip: To apply a Liquibase Pro 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 Pro 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 Pro extension uses a unique mongodb-pro XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

Tip: The preceding examples show only the mongo and mongoFile Change Types for Liquibase Pro. For a list of all Liquibase Pro 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.