Connect Liquibase MongoDB Secure with MongoDB Community and Enterprise Server

Last updated: September 2, 2025

MongoDB offers several NoSQL database products. This guide describes how to use Liquibase MongoDB Secure with MongoDB Community Server and MongoDB Enterprise Server. You need a Liquibase Secure license key to use it.

This guide does not imply support for third-party clones or emulations of MongoDB. For a tutorial on using Liquibase with Amazon DocumentDB, see Connect Liquibase MongoDB Secure with Amazon DocumentDB. This guide also does not describe the community-maintained Liquibase MongoDB extension. For information on that extension, see Contribute Docs: Use Liquibase with MongoDB.

Verified database versions

  • 8

  • 7

  • 6

  • 5

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

Deprecated versions

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

Before you begin

Note: mongosh is required to use Liquibase MongoDB Secure 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 Secure features.

Procedure

1

(Maven users only) Configure Maven

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. When configured this way, Maven automatically downloads the specified JAR files from Maven Central during the build process.

2

Configure your connection

Specify the database URL in the file (defaults file), along with other properties you want to set a default value for. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard connection format.

Be sure to change your_database to the name of the authenticating database.

url: mongodb://hostname:27017/your_database

Note: If you are unsure about how to configure the url property, refer to Connection String URI Format.

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 Secure 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 Secure extension uses a unique mongodb-secure XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

The MongoDB Secure extension lets you use MongoDB's native language of MongoDB Query Language (MQL), which you may be storing in JavaScript files, in Liquibase changesets and Change Types. This is possible because MongoDB Shell (mongosh) is compatible with Liquibase Secure. For more information, see MongoDB: Write Scripts. Example syntax:

db.createCollection('customers');

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

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. 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.

4. From a database UI tool, ensure that your database contains the myCollection object you added along with the DATABASECHANGELOG collection and DATABASECHANGELOGLOCK collection.

You can use MongoDB Compass to view collections in your database easily. For example, run the commands use myDatabase and db.myCollection.find().

Now you're ready to start deploying database changes with Liquibase!

Connect Liquibase MongoDB Secure with MongoDB Community and Enterprise Server - Liquibase