Using Liquibase MongoDB Pro with Amazon DocumentDB

You can use Liquibase Pro with Amazon DocumentDB, which is a NoSQL database that offers partial MongoDB compatibility. You can use most of the same drivers, application code, and tools in Amazon DocumentDB as you do in MongoDB. There are some functional differences between MongoDB and Amazon DocumentDB, but you can configure your Liquibase project to work with DocumentDB with only a few tweaks.

Amazon DocumentDB emulates the MongoDB API while running over Amazon Aurora on the back-end. Your Amazon DocumentDB database contains one or more clusters containing your database instance. Clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC) environment.

You need a valid Liquibase Pro license key to use Liquibase with Amazon DocumentDB through the MongoDB Pro Extension. If you want to use Liquibase Pro with MongoDB instead of Amazon DocumentDB, see Using Liquibase MongoDB Pro with MongoDB Community and Enterprise Server.

Verified versions

Amazon DocumentDB versions do not correspond directly to MongoDB versions. Liquibase has been tested on the following Amazon DocumentDB version:

• 4.0

For more information on Liquibase Pro and MongoDB version requirements, see Verified versions.

Verification level

Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Open Source and Liquibase Pro. For more information, see Database Verification Levels.

Foundational: Database has been tested and validated to deliver the basic functionality of change management and change tracking aligned with the database. Some additional advanced capabilities may be implemented. The Liquibase customer support team provides how-to/usage support around verified capabilities for commercial customers.

Prerequisites

1. Introduction to Liquibase – Dive into Liquibase concepts.
2. Install Liquibase – Download Liquibase on your machine.
3. Get Started with Liquibase – Learn how to use Liquibase with an example database.
4. Design Your Liquibase Project – Create a new Liquibase project folder and organize your changelogs
5. How to Apply Your Liquibase Pro License Key – If you use Liquibase Pro, activate your license.

Install drivers

To use Liquibase and Amazon DocumentDB (with MongoDB compatibility), you must download the JAR file that contains the Liquibase MongoDB Pro extension and the JDBC drivers.

To use the Liquibase CLI, place your JAR file(s) in the liquibase/lib directory.

If you use Maven, you must instead include the driver JAR as a dependency in your pom.xml file.

<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-commercial-mongodb</artifactId>
    <version>1.3.0</version>
</dependency>

Implement Amazon DocumentDB

1. Ensure that your desired Role Based Access Controls (RBAC) are established before continuing.
2. Download and Install mongosh if it is not already installed on your machine.

Note: mongosh is mandatory to use MongoDB with Liquibase Pro and it must be accessible to Liquibase. We recommend that mongosh is in the system PATH environment variable. If it is not, that location of mongosh must be manually specified in the liquibase.mongosh.conf file.

3. Download Java 11. The MongoDB Pro Extension requires it.

Tip: Java 11 may already be present on your machine if you used the installer to install Liquibase. We recommend installing Liquibase with Java 11 with the installer asset available on GitHub.

4. Set the supportsValidator argument to false in one of the following ways:
   • Command line: --supports-validator=false
   • liquibase.properties file: liquibase.mongodb.supportsValidator: false
   • Environment variable: LIQUIBASE_MONGODB_SUPPORTS_VALIDATOR=false
5. Set the retryWrites argument to false in one of the following ways:
   • 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.
6. (Optional) If you are using TLS/SSL, configure the TLS/SSL encrypted connection for Amazon DocumentDB. For a step-by-step guide, see the below drop down guide

Test your connection

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 a default value 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: jdbc:mongodb://localhost:27070/lbcat?tls=true&tlsAllowInvalidHostnames=true&retryWrites=false&tlsCAFile=rds-combined-ca-bundle.pem

TLS off:

url: jdbc: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>

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

In each changeset, you must specify the mongosh native executor using the runWith attribute:

• Formatted Mongo: runWith:mongosh
• XML: runWith="mongosh"
• YAML: runWith: mongosh
• JSON: "runWith": "mongosh"

Alternatively, you can use native mongosh scripts directly with Liquibase. The MongoDB Pro extension lets you use MongoDB's native language of JavaScript in changesets and Change Types. This is possible because MongoDB Shell (mongosh) is compatible with Liquibase Pro. For more information, see MongoDB: Write Scripts. Example syntax:db.createCollection('customers');

You can use XML, YAML, or JSON "modeled" changelogs instead of writing plain or Formatted Mongo scripts in JavaScript. XML, YAML, and JSON changelogs have all the functionality of a Formatted Mongo changelog, like specifying metadata tags and including other changelogs. You must specify mongosh as the value of runWith in each changeset.

In a modeled changelog, you can specify mongosh code within the mongo and mongoFile Change Types. Liquibase then implements this in your database. However, the actual mongosh you specify is the same as in Formatted Mongo.

If you want to use the include or includeAll tag in a root changelog, it must be an XML, YAML, or JSON file. The child changelogs you reference can be written in Formatted Mongo, XML, YAML, or JSON.

• Formatted mongosh example
• XML example
• YAML example
• JSON example

With the Liquibase MongoDB Pro extension 1.3.0+, you can use a formatted Mongo changelog for MongoDB Pro, similar to a formatted SQL changelog. This lets you use mongosh scripts written in JavaScript directly in Liquibase.

All Liquibase formatted Mongo changelogs must use the file extension .JS or .js. They must also begin with a changelog header: // liquibase formatted mongodb. Your changesets must each specify runWith:mongosh. For example:

// liquibase formatted mongodb

// changeset your.name:1 labels:example-label context:example-context runWith:mongosh
// comment: example comment

db.createCollection('customers');

// rollback db = db.person.drop()

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:

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:mongodb-pro="http://www.liquibase.org/xml/ns/pro-mongodb"
    xmlns:mongodb="http://www.liquibase.org/xml/ns/mongodb"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
    http://www.liquibase.org/xml/ns/pro-mongodb http://www.liquibase.org/xml/ns/pro-mongodb/liquibase-pro-mongodb-latest.xsd
    http://www.liquibase.org/xml/ns/mongodb http://www.liquibase.org/xml/ns/mongodb/liquibase-mongodb-latest.xsd">

    <changeSet id="1" author="your.name" runWith="mongosh">
        <mongodb-pro:mongo dbms="mongodb">
            db.createCollection('person')
        </mongodb-pro:mongo>

        <rollback>
            <mongodb-pro:mongo>
                db.person.drop()
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>

    <changeSet id="2" author="your.name" runWith="mongosh">
        <mongodb-pro:mongoFile dbms="mongodb" path="scriptFile.txt" relativeToChangelogFile="true"/>

        <rollback>
            <mongodb-pro:mongo>
                db.company.drop()
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>

</databaseChangeLog>

databaseChangeLog:
  - changeSet:
      id: 1
      author: your.name
      runWith: mongosh
      changes:
        - mongo:
            mongo: "db.createCollection('person')"
            dbms: mongodb
        - rollback:
            mongo:
              mongo: "db.person.drop()"

  - changeSet:
      id: 2
      author: your.name
      runWith: mongosh
      changes:
        - mongoFile:
            path: "scriptFile.txt"
            dbms: mongodb
            relativeToChangelogFile: "true"
        - rollback:
            mongo:
              mongo: "db.company.drop()"

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "your.name",
        "runWith": "mongosh",
        "changes": [
          {
            "mongo": {
              "dbms": "mongodb",
              "mongo": "db.createCollection('person')"
            }
          }
        ],
        "rollback": [
          {
            "mongo": {
              "mongo": "db.person.drop()"
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "2",
        "author": "your.name",
        "runWith": "mongosh",
        "changes": [
          {
            "mongoFile": {
              "dbms": "mongodb",
              "path": "scriptFile.txt",
              "relativeToChangelogFile": true
            }
          }
        ],
        "rollback": [
          {
            "mongo": {
              "mongo": "db.company.drop()"
            }
          }
        ]
      }
    }
  ]
}

Alternatively, you can specify some Change Type behavior using the MongoDB Liquibase Open Source syntax, which is included in your MongoDB Liquibase Pro installation. These Change Types run corresponding commands in MongoDB. This syntax is only valid for XML, YAML, and JSON changelogs.

For a list of all Pro and OSS MongoDB Change Types and full syntax examples, see Liquibase Change Types for MongoDB.

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

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.

5. Then make 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.

6. From a database UI tool, ensure that your database contains the myCollection object you added along with the DATABASECHANGELOG collection and DATABASECHANGELOGLOCK collection.

Tip: You can use MongoDB Compass to easily view collections in your database. For example, run the commands use myDatabase and db.myCollection.find().

Now you're ready to start making deployments with Liquibase!

Related links

• Using Liquibase MongoDB Pro with MongoDB Community and Enterprise Server
• AWS DocumentDB: MongoDB Compatibility
• MongoDB: Comparing Amazon DocumentDB and MongoDB