Using Liquibase MongoDB Pro with MongoDB Atlas

MongoDB Atlas is a fully managed cloud database service provided by MongoDB, Inc. It allows users to deploy, manage, and scale MongoDB databases without the need to handle the underlying infrastructure.

Verified database versions

  • 7
  • 6
  • 5

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

Prerequisites

Learn more about each step at the links below.

  1. Create a MongDB Atlas Account
  2. Deploy a Free Cluster
  3. Add Your Connection IP Address to Your IP Access List

Configure MongoDB

  1. Ensure that your Configuring User Roles for MongoDB Pro are established before continuing.
  2. Download and Install mongosh if it is not already installed on your machine.

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

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

Install drivers

CLI users

To use Liquibase and MongoDB Atlas, 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.

Maven users

To use Liquibase with Maven, you must instead include the driver JAR(s) as a dependency in your pom.xml file. Using this information, Maven automatically downloads the driver JAR from Maven Central when you build your project. 

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

Configure connection

  1. Ensure your MongoDB database is configured. See Install MongoDB for more information.

  2. Ensure your Liquibase Pro license key is specified. For example, in a liquibase.properties file (defaults file):

    licenseKey: zQl8kNZjZgSp9LvqWQFAtGwiHrpg97UyAfQrNSiJQBCDH8FQPdDzANUpIe4Bj3CZA2IXgDBaoYZFvMw0E/s4JcECB3/A6jO+...

  3. Choose an authentication method. This guide includes SCRAM (username/password), X.509 Certificate, and AWS IAM.

    4. Users may prefer the SCRAM method because of simplicity and increased security. The server stores passwords in a iterated hash format. This makes offline attacks harder, and decreases the impact of database breaches.

    MongoDB Atlas configuration

    1. Create a Database User for Your Cluster
    2. Add or change Database User role to Atlas admin (Security > Database Access > Edit > Database User Privileges > Built-in Role)

      3. Note: Learn more about database users and built in roles here: Modify Database Users and Built In Roles.

    Liquibase configuration

    Once MongoDB Atlas is configured, you must then configure Liquibase.

    1. Add the liquibase.command.url property to the properties file, environment variables, or command line options in the following format:
      2. liquibase.command.url: mongodb+srv://cluster0.abcd123.mongodb.net/lbcat
    2. Add the liquibase.command.username and liquibase.command.password properties to the same configuration file, environment variables, or command line. These are the same credentials entered in Step 1 above titled: Create a Database User for Your Cluster

    This authorization mechanism allows system administrators to configure certificates for users within their organization. It also does not require you to memorize a password.

    MongoDB Atlas configuration

    1. Add Database Users for X.509 Certificates
    2. Add or change Database User role to Atlas admin (Security > Database Access > Edit > Database User Privileges > Built-in Role)

      3. Note: Learn more about database users and built in roles here: Modify Database Users and Built In Roles.

    Java configuration

    Java Truststore is a Java mechanism that stores Certificates. It is used only by Java applications. The below command creates the CA.p12 Truststore file that contains the certificate which was pulled from MongoDB Atlas above in Step 4.

    1. Create the Truststore file by running the following in the CLI:
      2. openssl pkcs12 -export -in X509-cert-137983036943191321.pem -name mongoAtlas -caname CA -out CA.p12 -passout pass:qwerty123

    The CA.p12 Truststore file that contains the certificate can now be used by Liquibase to connect to MongoDB Atlas.

    Liquibase configuration

    Once MongoDB Atlas and Java are configured, you must then configure Liquibase.

    Note: Your connection to MongoDB Atlas must be TLS and SSL encrypted.

    1. Add the liquibase.command.url property to the properties file, environment variables, or command line options in the following format:
      2. liquibase.command.url: mongodb+srv://cluster0.xtsabc123.mongodb.net/lbcat?authSource=%24external&authMechanism=MONGODB-X509&&tlsCertificateKeyFile=X509-cert-137983036943191321.pem
    2. Add the following to the environment variables before running Liquibase commands:
      3. JAVA_OPTS="-Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=CA.p12 -Djavax.net.ssl.keyStorePassword=qwerty123"

    AWS lets you configure credentials using IAM (Identity and Access Management) roles, which can offer better security and simplify your credential management process.

    MongoDB Atlas configuration

    Follow the steps in the MongoDB documentation Set Up Authentication with AWS IAM:

    1. Set Up Authentication with AWS IAM Roles
    2. Grant Database Access to AWS IAM Roles
    3. Connect to Atlas Cluster Using AWS IAM

    Liquibase configuration

    1. Ensure your Liquibase Pro license key is specified. For example, in a liquibase.properties file (defaults file):

      licenseKey: zQl8kNZjZgSp9LvqWQFAtGwiHrpg97UyAfQrNSiJQBCDH8FQPdDzANUpIe4Bj3CZA2IXgDBaoYZFvMw0E/s4JcECB3/A6jO+...
    2. Configure your properties file, environment variables, or command line options in the following format:
      3. liquibase.command.url=mongodb+srv://<atlas-host-name>/test?authSource=%24external&authMechanism=MONGODB-AWS
liquibase.command.username=<AWS_ACCESS_KEY_ID> # optional
liquibase.command.password=<AWS_SECRET_ACCESS_KEY> # optional

Test connection

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

    2. 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 MongoDB Query Language (MQL), which you may be storing in JavaScript files, in Liquibase 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 files. 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 (MongoDB Query Language) code within the mongo and mongoFile Change Types. Liquibase then implements this in your database. However, the actual MQL you specify is the same as in Formatted Mongo changelogs.

    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.

    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 MongoDB Query Language (MQL) directly in Liquibase.

    All Liquibase formatted Mongo changelogs must use the file extension .JS or .js (JavaScript). 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.

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

    3. 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. Then execute these 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 collection and DATABASECHANGELOGLOCK collection.

    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