Using Liquibase with the MongoDB Pro Extension

Note: The MongoDB Pro extension requires Liquibase 4.20+. It is only available to Liquibase Pro users. This extension requires Java 11.

The MongoDB Pro extension streamlines the workflow for MongoDB users. It allows you to use MongoDB's native language in changesets and Change Types. All of this is possible because MongoDB Shell (mongosh) is compatible with Liquibase Pro. MongoDB also supports Targeted Rollback, Flows, and changelog-level quality checks with Liquibase Pro. Learn the details and how to implement this functionality below.

This guide is intended for use with MongoDB products and services provided directly by MongoDB, Inc. This includes MongoDB Atlas, MongoDB Enterprise Server, and MongoDB Community Server. It does not imply support for third-party clones or emulations of Mongo.

Features

Some Liquibase functionality is different with the MongoDB Pro Extension than with other databases:

  • As of Liquibase Pro 4.20.1, JSON and YAML changelogs are supported along with the legacy support of XML changelogs.
  • MongoDB is a NoSQL database, which means you are unable to use any commands that generate SQL output. Learn more about Liquibase Commands here.
    • Rollback commands are supported except for commands that generate SQL output.
    • Change tracking commands are supported except for commands that generate SQL output.
  • Quality Check functionality that works with the MongoDB Pro Extension is limited to checks targeting the changelog scope. Learn more about Quality Checks here. The pre-packaged Quality Check content currently relevant to MongoDB are these two items:
  • mongo and mongoFile are the two new Change Types available to Liquibase. They require a user to configure the native executor, Mongo Shell (mongosh), prior to use.

Verified versions

MongoDB Tested Versions MongoDB Shell Tested Versions Liquibase Pro Compatible Version Supported Auth mechanisms
4.4.x 1.6.x
1.7.x
1.8.x - Recommended
4.19.0 and later SCRAM & x.509
5.x 1.6.x
1.7.x
1.8.x - Recommended
4.19.0 and later SCRAM & x.509
6.x 1.6.x
1.7.x
1.8.x - Recommended
4.19.0 and later SCRAM & x.509

Tip: LDAP and Kerberos Authentication are not supported at this time. Learn more about MongoDB Authentication here: authentication

Command support

MongoDB does not support the database inspection commands family or the *sql command variants (such as update-sql and changelog-sync-sql).

Liquibase Pro Quality Checks have limited support. Changelog-scoped quality checks are supported as long as they are not SQL-specific or relational-specific. Database-scoped quality checks are not supported because they are database-specific.

Supported quality checks:

  • RollbackRequired
  • ChangesetContextCheck
  • ChangesetCommentCheck
  • ChangesetLabelCheck
  • RequiredChangesetDisUUID
  • SqlUserDefinedPatternCheck

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.

Implement the MongoDB Pro extension

  1. If you have the current open source MongoDB version installed, remove it and the associated drivers from your machine.
  2. Ensure that your MongoDB Pro Extension User Roles are established before continuing.
  3. Download and Install mongosh if it is not already installed on your machine.

    Tip: We suggest that you add mongosh to the system PATH environment variable.

    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.

  4. Download Java 11, this 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.

  5. Download the JAR file that contains the MongoDB Pro Extension and drivers from Maven Central.

    Note: If you are a Maven user, do not download the MongoDB Pro Extension JAR file. You only need to specify the dependency listed below in your pom.xml file and all required artifacts will download by Maven.

    <dependency>
        <groupId>org.liquibase.ext</groupId>
        <artifactId>liquibase-commercial-mongodb</artifactId>
        <version>1.0.0</version>
    </dependency>
  6. Extract the single liquibase-commercial-mongodb-1.0.0.jar file and place it in the liquibase/lib directory.
  7. Apply your Liquibase Pro key. See How to Apply Your Liquibase Pro License Key

Configure your TLS/SSL encrypted connection

If you are using TLS/SSL, configure the TLS/SSL encrypted connection for the MongoDB Pro extension.

Tip: This is only required if you are using SSL/TLS because it is active on your Mongo server or because you are using MongoDB Atlas.

  1. Configure the MongoDB instance by first following Mongo's configuration guide.
  2. Then verify that it works by following Mongo's verification guide.
  3. 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.
  4. 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.

  5. Add the url parameter to the CLI, liquibase.properties file, or set it as an environment variable:

    Example: liquibase.properties file:
    liquibase.command.url=mongodb+srv://<hostname>/<database>
    liquibase.command.url: mongodb://localhost:27017/lbcat?tls=true&tlsCAFile=mongodb.pem

    Environment variable:
    LIQUIBASE_COMMAND_URL=mongodb+srv://<hostname>/<database>
    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 connecting Liquibase with the MongoDB Pro Extension, 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 Pro 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/cacerts

Test your connection

  1. Ensure your MongoDB database is configured. See Install MongoDB for more information.
  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. url: mongodb://hostname:27017/myDatabase

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

    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. Note: The use of JSON and YAML changelogs is available in Liquibase Pro MongoDB commercial version 1.0.0.

  3. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
  4. 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.
  5. Then make changes to your database with the update command:
  6. 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.
  7. From a database UI tool, ensure that your database contains the myCollection object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.
  8. 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