MongoDB Atlas
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
- 6
- 5
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.
- Create a MongDB Atlas Account
- Deploy a Free Cluster
- Add Your Connection IP Address to Your IP Access List
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.
- 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
JAVA_OPTS="-Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=CA.p12 -Djavax.net.ssl.keyStorePassword=qwerty123"
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
MongoDB Atlas is now configured successfully with Liquibase.