MongoDB Pro and 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 with the MongoDB Pro Extension.

Verified versions

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

  • 4.0

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.

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.0.0</version>
</dependency>

Implement Amazon DocumentDB

  1. Download and Install mongosh if it is not already installed on your machine.

    2. 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.

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

    3. 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.

  3. 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
  4. 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.
  5. (Optional) If you are using TLS/SSL, configure the TLS/SSL encrypted connection for Amazon DocumentDB. For a step-by-step guide, see MongoDB Pro and Amazon DocumentDB TLS/SSL Configuration.

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 JDBC format:

    3. 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>

  1. Create a text file called changelog (.xml) in your project directory and add a changeset.

    If you already created a changelog using the init project command, you can use that instead of creating a new file. When adding onto an existing changelog, be sure to only add the changeset and to not duplicate the changelog header.

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

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

    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:

    <?xml version="1.0" encoding="UTF-8"?>
<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"
    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">
    <changeSet id="1" author="nvoxland" runWith="mongosh">
        <mongodb-pro:mongo>
            db = db.getSiblingDB( 'mydb' );
            db.createCollection('person2');
        </mongodb-pro:mongo>
        <rollback>
            <mongodb-pro:mongo>
                db = db.getSiblingDB( 'mydb' );
                db.person2.drop();
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>
    <changeSet id="2" author="nvoxland" runWith="mongosh">
        <mongodb-pro:mongoFile path="scriptFile.js" relativeToChangelogFile="true"/>
        <rollback>
            <mongodb-pro:mongoFile path="scriptFile-rollback.js" relativeToChangelogFile="true"/>
        </rollback>
    </changeSet>
    <changeSet id="3" author="nvoxland" runWith="mongosh">
        <mongodb-pro:mongo>
            db.products.insertMany( [
            { item: "card", qty: 15 },
            { item: "envelope", qty: 20 },
            { item: "stamps" , qty: 30 }
            ] );
        </mongodb-pro:mongo>
        <rollback>
            <mongodb-pro:mongo>
                db.products.deleteMany( { } );
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>
</databaseChangeLog>
    databaseChangeLog:
- changeSet:
      id:  1
      author:  your.name
      runWith:  mongosh
      labels: example-label
      context: example-context
      comment: example-comment
      changes:
       - createTable:
            tableName:  person
            columns:
              - column:
                  name:  id
                  type:  int
                  autoIncrement:  true
                  constraints:
                    primaryKey:  true
                    nullable:  false
              - column:
                  name:  name
                  type:  varchar(50)
                  constraints:
                    nullable:  false
              - column:
                  name:  address1
                  type:  varchar(50)
              - column:
                  name:  address2
                  type:  varchar(50)
              - column:
                  name:  city
                  type:  varchar(30)

- changeSet:
      id:  2
      author:  your.name
      runWith:  mongosh
      labels: example-label
      context: example-context
      comment: example-comment
      changes:
       - createTable:
            tableName:  company
            columns:
              - column:
                  name:  id
                  type:  int
                  autoIncrement:  true
                  constraints:
                    primaryKey:  true
                    nullable:  false
              - column:
                  name:  name
                  type:  varchar(50)
                  constraints:
                    nullable:  false
              - column:
                  name:  address1
                  type:  varchar(50)
              - column:
                  name:  address2
                  type:  varchar(50)
              - column:
                  name:  city
                  type:  varchar(30)

- changeSet:
      id:  3
      author:  other.dev
      runWith:  mongosh
      labels: example-label
      context: example-context
      comment: example-comment
      changes:
       - addColumn:
            tableName:  person
            columns:
              - column:
                  name:  country
                  type:  varchar(2)
    {
  "databaseChangeLog": [
    ---------------------------CREATE AND DROP COLLECTION---------------------------
    {
      "changeSet": {
        "id": "1",
        "author": "as",
        "runWith": "mongosh",
        "labels": "test_label",
        "context": "test_context",
        "comment": "test_comment",
        "changes": [
          {
            "createCollection": {
              "collectionName": "countries_json"
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "2",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "dropCollection": {
              "collectionName": "towns_json"
            }
          }
        ],
        "rollback": ""
      }
    },
    ---------------------------INSERT ONE--------------------------
    {
      "changeSet": {
        "id": "3",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "insertOne": {
              "collectionName": "towns_json",
              "document": {
                "$rawJson": {
                  "name": "New York",
                  "population": 222000000,
                  "famousFor": [
                    "the MOMA",
                    "food",
                    "Derek Jeter"
                  ],
                  "mayor": {
                    "name": "Bill de Blasio",
                    "party": "D"
                  }
                }
              }
            }
          }
        ],
        "rollback": ""
      }
    },
    ---------------------------INSERT MANY-------------------------
    {
      "changeSet": {
        "id": "4",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "insertMany": {
              "collectionName": "countries_json",
              "documents": {
                "$rawJson": [
                  {
                    "_id": "us",
                    "name": "United States",
                    "exports": {
                      "foods": [
                        {
                          "name": "bacon",
                          "tasty": "true"
                        },
                        {
                          "name": "burger"
                        }
                      ]
                    }
                  },
                  {
                    "_id": "ca",
                    "name": "Canada",
                    "exports": {
                      "foods": [
                        {
                          "name": "bacon",
                          "tasty": false
                        },
                        {
                          "name": "syrup",
                          "tasty": true
                        }
                      ]
                    }
                  },
                  {
                    "_id": "mx",
                    "name": "Mexico",
                    "exports": {
                      "foods": [
                        {
                          "name": "salsa",
                          "tasty": true,
                          "condiment": true
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        ],
        "rollback": {
          "runCommand": {
            "command": "{ delete: \"countries_json\", deletes: [{q: { }, limit: 0}] }"
          }
        }
      }
    },
    ---------------------------CREATE AND DROP INDEX---------------------------
    {
      "changeSet": {
        "id": "5",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "createIndex": {
              "collectionName": "countries_json",
              "keys": {
                "$rawJson": {
                  "name": 1,
                  "type": 1
                }
              },
              "options": {
                "$rawJson": {
                  "unique": true,
                  "name": "ui_countries_json"
                }
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "6",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "dropIndex": {
              "collectionName": "countries_json",
              "keys": {
                "$rawJson": {
                  "name": 1,
                  "type": 1
                }
              },
              "options": {
                "$rawJson": {
                  "unique": true,
                  "name": "ui_countries_json"
                }
              }
            }
          }
        ]
      }
    },
    ---------------------------RUN COMMAND---------------------------
    {
      "changeSet": {
        "id": "7",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "runCommand": {
              "command": "{ buildInfo: 1 }"
            }
          }
        ],
        "rollback": ""
      }
    },
    ---------------------------ADMIN COMMAND---------------------------
    {
      "changeSet": {
        "id": "8",
        "author": "as",
        "runWith": "mongosh",
        "changes": [
          {
            "adminCommand": {
              "command": "{ buildInfo: 1 }"
            }
          }
        ],
        "rollback": ""
      }
    }
  ]
}
  2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
    3. 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_jdbc_url>
Liquibase command 'status' was executed successfully.
  3. Then make changes to your database with the update command:
    4. 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.
  4. From a database UI tool, ensure that your database contains the myCollection object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

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