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 database versions

  • 7
  • 6
  • 5

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

Deprecated versions

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

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

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>

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. Ensure your Liquibase Pro license key is specified. For example, in a liquibase.properties file (defaults file):

    licenseKey: zQl8kNZjZgSp9LvqWQFAtGwiHrpg97UyAfQrNSiJQBCDH8FQPdDzANUpIe4Bj3CZA2IXgDBaoYZFvMw0E/s4JcECB3/A6jO+...
  2. Add the liquibase.command.url property to the properties file, environment variables, or command line options in the following format:
    3. liquibase.command.url: mongodb+srv://cluster0.abcd123.mongodb.net/lbcat
  3. 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