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.
- Create a MongDB Atlas Account
- Deploy a Free Cluster
- 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.
liquibase/lib
directory.
Maven users
To use Liquibase with Maven, 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
- Create a Database User for Your Cluster
- Add or change Database User role to Atlas admin (Security > Database Access > Edit > Database User Privileges > Built-in Role)
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.
-
Ensure your Liquibase Pro license key is specified. For example, in a
liquibase.properties
file (defaults file):licenseKey: zQl8kNZjZgSp9LvqWQFAtGwiHrpg97UyAfQrNSiJQBCDH8FQPdDzANUpIe4Bj3CZA2IXgDBaoYZFvMw0E/s4JcECB3/A6jO+...
- Add the
liquibase.command.url
property to the properties file, environment variables, or command line options in the following format: - Add the
liquibase.command.username
andliquibase.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
liquibase.command.url: mongodb+srv://cluster0.abcd123.mongodb.net/lbcat
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
- Add Database Users for X.509 Certificates
- Add or change Database User role to Atlas admin (Security > Database Access > Edit > Database User Privileges > Built-in Role)
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.
- Create the Truststore file by running the following in the CLI:
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.
- Add the
liquibase.command.url
property to the properties file, environment variables, or command line options in the following format: - Add the following to the environment variables before running Liquibase commands:
liquibase.command.url: mongodb+srv://cluster0.xtsabc123.mongodb.net/lbcat?authSource=%24external&authMechanism=MONGODB-X509&&tlsCertificateKeyFile=X509-cert-137983036943191321.pem
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.