Connect Liquibase MongoDB Pro with MongoDB Atlas

Last updated: July 14, 2025 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.

Verified database versions

  • 8

  • 7

  • 6

  • 5

Before you begin

Note: mongosh is required to use Liquibase MongoDB Pro features, including the <mongo> and <mongosh> Change types and Mongo changelogs. These features allow you to run native JavaScript-based MongoDB changes. To use mongosh, it must be made accessible to Liquibase. We recommend that you make sure mongosh is available in your system PATH. If not, its location must be manually specified using the liquibase.mongosh.conf file. While mongosh is not required; without it, your functionality will be limited, and you won’t be able to use advanced MongoDB Pro features.

Procedure

1

Install drivers

You do not need to install drivers if you are using the Liquibase MongoDB Pro extension. You will need to place the liquibase-commercial-mongodb-<version>. jar file in the $LIQUIBASE_HOME/lib directory. Use the buttons above to navigate to the required downloads and extract them to your Liquibase /lib folder.

Note: Do not specify a driver in the liquibase.properties file.

If you prefer, you can use environment variables to point to the directory where Liquibase is installed on your machine. You can set environment variables using your operating system's shell. The location of $LIQUIBASE_HOME will depend on where Liquibase was installed on your machine.

Note for Maven users: If you're running Liquibase using the Maven plugin using mvn liquibase:update, installing the extension with Maven ensures the right files are available and everything works together automatically. You can manage these extensions by adding them as dependencies in your project’s pom.xml file. Configuring Maven this way ensures that the necessary JAR files are retrieved from Maven Central during the build phase.

2

Configure your connection

Choose an authentication method. This guide includes SCRAM (username/password), X.509 Certificate, AWS IAM, and OIDC.

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

  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.

3

Test your connection

1. Create a text file called changelog (.sql, .yaml, .json, or .xml) in your project directory and add a changeset.

Native MongoDB Shell (mongosh) scripts in MongoDB Query Language (MQL): Let developers use Liquibase without modifying existing MQL scripts, which may be JavaScript (.js) files.

Formatted Mongo changelogs (MongoDB Pro 1.3.0+): Add Liquibase changeset metadata to your MQL scripts to use features like rollback, contexts, labels, and the include and includeAll tags. These must be saved as .js files.

YAML, JSON, and XML modeled changelogs: Specify changes for Liquibase to deploy without the need for MQL scripts. However, you can still deploy MQL scripts in YAML, JSON, and XML changelogs by using the mongo and mongoFile Change Types. Using these Change Types requires you to specify mongosh as the value of the runWith attribute for all mongo and mongoFile changesets.

Note for XML: The Liquibase MongoDB Pro extension uses a unique mongodb-pro XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

db.createCollection('customers');

Tip: The preceding examples show only the mongo and mongoFile Change Types for Liquibase Pro. For a list of all Liquibase Pro and Liquibase Open Source Change Types for MongoDB, including Change Types that you can without the mongosh native executor, see Liquibase Change types for MongoDB.

2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

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_connection_url> Liquibase command 'status' was executed successfully.

3. Inspect the deployment SQL with the update-sql command

liquibase update-sql --changelog-file=<changelog.xml>

If the SQL that Liquibase generates isn't what you expect, you should review your changelog file and make any necessary adjustments.

4. Then execute these changes to your database with the update command:

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.

5. From a database UI tool, ensure that your database contains the test_table object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.