Using Liquibase MongoDB Pro with MongoDB Community and Enterprise Server

MongoDB offers several NoSQL database products. This guide describes how to use Liquibase MongoDB Pro with MongoDB Community Server and MongoDB Enterprise Server. You need a Liquibase Pro license key to use it.

This guide does not imply support for third-party clones or emulations of MongoDB. For a tutorial on using Liquibase with Amazon DocumentDB, see Using Liquibase MongoDB Pro with Amazon DocumentDB. This guide also does not describe the community-maintained Liquibase MongoDB extension. For information on that extension, see Contribute Docs: Use Liquibase with MongoDB.

Verified database versions

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

Deprecated versions

MongoDB 4.4.x is deprecated as of February 29, 2024.

Prerequisites

Download and Install Liquibase on your machine.
Ensure Java is installed: Liquibase requires Java to run. If you used the Liquibase Installer, Java is included automatically. Otherwise, you must install Java manually.
If you use Liquibase Pro, or a Liquibase Pro extension, confirm that you have a valid license key. For more information, see How to Apply Your Liquibase Pro License Key

Download the extension

Download the latest version of the Liquibase MongoDB Pro Extension here.

Configure MongoDB

Configure User Roles for MongoDB before continuing.
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.

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.

(Optional) Configure encrypted database connection with TLS/SSL

Tip: TLS/SSL is not required to use Liquibase Pro and MongoDB. This is only required if you are using TLS/SSL because it is active on your MongoDB server or because you are using MongoDB Atlas.

To configure the TLS/SSL encrypted connection for the MongoDB Pro extension:

Configure the MongoDB instance by first following Mongo's configuration guide.
Verify that it works by following Mongo's verification guide.
Add the --tlsCertificateKeyFile certificate that is produced in the configuration step above to the Java keystore. The --tlsCertificateKeyFile specifies the .pem file that contains mongosh's certificate.

On Linux:

sudo keytool -importcert -trustcacerts -file PATH_TO_CERT_FILE/mongodb-cert.crt -cacerts -storepass changeit -alias MongoDB

On Windows, open terminal in Administrator mode and run:

keytool -importcert -trustcacerts -file PATH_TO_CERT_FILE\\mongodb-cert.crt -cacerts -storepass changeit -alias mongodb

Note: The default password for keystore is changeit.

Specify your TLS connection information in the Liquibase --url argument, using the format mongodb+srv://<hostname>/<database>. You can pass this argument in CLI, liquibase.properties file, or set it as an environment variable:

Example: liquibase.properties file:
liquibase.command.url=mongodb://localhost:27017/lbcat?tls=true&tlsCAFile=mongodb.pem

Environment variable:
LIQUIBASE_COMMAND_URL=mongodb://localhost:27017/lbcat?tls=true&tlsCAFile=mongodb.pem

If you are using a Java keystore that is not the default, you must add the necessary environment variables before running Liquibase commands.

On Linux:
```
export JAVA_OPTS="-Djavax.net.ssl.keyStore=PATH_TO_KEYSTORE/cacerts -Djavax.net.ssl.keyStorePassword=PASSWORD"
```
On Windows:
```
set JAVA_OPTS=-Djavax.net.ssl.keyStore="PATH_TO_KEYSTORE\\cacerts" -Djavax.net.ssl.keyStorePassword=PASSWORD
```
Do not use setx as it adds keyStorePassword to system environment variables.

Troubleshooting errors

After configuring TLS/SSL for Liquibase and MongoDB, you may come across an error that states:

Error: Could not find or load main class Files\\Java\\{jdk-version}.security.cacerts Caused by: java.lang.ClassNotFoundException: Files\\Java\\{jdk-version}.security.cacerts

This means that Liquibase is struggling to find the certification file. To resolve the issue, run the following command in the CLI:

On Windows:

set JAVA_OPTS=-Djavax.net.ssl.keyStore="%JAVA_HOME%\\lib\\security\\cacerts"

On Linux:

export JAVA_OPTS=-Djavax.net.ssl.keyStore=$JAVA_HOME/lib/security/cacertsInstall drivers

CLI users

Pro extension users do not need to install drivers as long as you have placed the liquibase-commercial-mongodb-<version>. jar file in the liquibase/lib directory.

To use Liquibase Pro and Amazon DocumentDB (with MongoDB compatibility), you should not specify a driver in the liquibase.properties file so that Liquibase recognizes the correct one.

Maven users

Include the liquibase-commercial-mongodb-<version>. jar file as a dependency in your pom.xml file. Using this information, Maven automatically downloads any required JAR files from Maven Central when you build your project.

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

Configure connection

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

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

licenseKey: zQl8kNZjZgSp9LvqWQFAtGwiHrpg97UyAfQrNSiJQBCDH8FQPdDzANUpIe4Bj3CZA2IXgDBaoYZFvMw0E/s4JcECB3/A6jO+...

Specify the database URL in the 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.
Be sure to change myDatabase to the name of the authenticating database.

url: mongodb://hostname:27017/myDatabase

Note: If you are unsure about how to configure the url property, refer to Connection String URI Format.

Test connection

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

You can write Liquibase changelogs in the MongoDB Pro extension in these ways:

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.

Raw mongosh example

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');

Formatted mongosh 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 MongoDB Query Language (MQL) directly in Liquibase while also having access to all Liquibase features.

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.customers.drop()

YAML example

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()"

JSON example

{
  "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()"
            }
          }
        ]
      }
    }
  ]
}

XML example

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>

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.

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.

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.

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 deploying database changes with Liquibase!

Using Liquibase MongoDB Pro with MongoDB Community and Enterprise Server

Verified database versions

Deprecated versions

Prerequisites

Download the extension

Configure MongoDB

Troubleshooting errors

CLI users

Maven users

Configure connection

Test connection

Raw mongosh example

Related links