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.

This guide covers two ways to authenticate a MongoDB Atlas instance with Liquibase. One uses the SCRAM (username/password) method and the other uses the X.509 Certificate method. Follow the one that fits your scenario best.

Verified versions

Atlas is currently running v7+

  • 7
  • 6
  • 5

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

Deprecated versions

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

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

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
  4. Download the JAR file that contains the MongoDB Pro extension and drivers from Maven Central. 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.

SCRAM (Username/Password)

Users often 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

MongoDB Atlas is now configured successfully with Liquibase.

X.509 Certificate

This authorization mechanism, albeit more complex, 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"

MongoDB Atlas is now configured successfully with Liquibase.

Related links