Using Liquibase MongoDB Pro with MongoDB Platforms

MongoDB is a NoSQL (non-relational) database. MongoDB Pro provides the ability to work with native mongosh scripts.

You can use Liquibase with several MongoDB providers, including MongoDB Atlas, MongoDB Community Server, MongoDB Enterprise Server, and the Amazon DocumentDB clone. The Liquibase MongoDB Pro extension lets you use all the features of Liquibase Pro with MongoDB, including Policy Checks, Secrets Management, and Structured Logging. These features enhance your database's security, reliability, and compatibility with other tools in your development pipeline.

Using Liquibase with MongoDB is similar to using it with other databases. You still track changes within changesets in changelogs, and use commands such as update and rollback to deploy changes and manage your database. However, because MongoDB does not use SQL, you cannot use SQL changelogs or Liquibase commands that generate SQL output.

You can write Liquibase changelogs in the MongoDB Pro extension in three ways:

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

To learn how to specify changes in each format, see Use Native Executors with MongoDB Pro.

Getting started tutorials

To learn how to configure the Liquibase MongoDB Pro extension with your installation of MongoDB, see the following topics:

Tip: To use the community-maintained Liquibase MongoDB extension, see Contributors Docs: MongoDB Extension.

Features

The MongoDB Pro extension supports all the features of Liquibase that are supported in the MongoDB Open Source extension. In addition, MongoDB Pro lets you use Liquibase Pro features including:

  • Policy Checks: automatically analyze your changelogs for desired format and behavior to increase deployment success rates and uphold security best practices
  • Secrets Management: keep your authentication data secure by integrating with third-party secrets vaults
  • Structured Logging: improve your database observability by easily reading Liquibase data in your favorite analytics tool
  • Operation Reports: generate reports of operations you perform on your database
  • Flow Files: create repeatable, portable, and platform-independent Liquibase workflows to run in any of your CI/CD tools
  • Remote file access: centralize file management with AWS S3 to build a reusable repository of Liquibase files you can update and retrieve
  • Targeted rollback: avoid collateral damage by specifying which changesets in your changelog to undo

Change Types

You can use many of the standard Liquibase Change Types in MongoDB Pro. The two new Change Types available are mongo and mongoFile, which allow you to specify native Mongo scripts in XML, YAML, and JSON changelogs. They require the user to configure the native executor, Mongo Shell (mongosh), prior to use.

For a list of unique Change Types in the Liquibase Pro extension for MongoDB, see Liquibase Change Types for MongoDB. In addition to the Pro Change Types, you can use several Change Types from the Liquibase Open Source extension.

Supported commands

MongoDB supports the following commands:

  • Update commands, except those that generate SQL output. For example, update and update-count are supported.
  • Rollback commands, except those that generate SQL output. For example, rollback and rollback-one-changeset are supported.
  • Change tracking commands, except those that generate SQL output. For example, changelog-sync, status, and history are supported.
    • The connect command is supported in MongoDB Pro 1.4.0+.
  • Policy checks commands. For example, copy, show, and run are supported.
  • All other commands, unless otherwise specified in the Limitations section.

For more information, see Liquibase Commands.

Supported policy checks

You can use changelog-scoped policy checks in MongoDB Pro. For example:

Changelog-scoped policy checks are supported as long as they are not SQL-specific or relational-specific. The following is a full list of policy checks supported on MongoDB:

Limitations

  • The child MongoDB scripts referenced by the include and includeAll tags must contain the changeset decoration and the following minimum changeset metadata, author:id and runWith:mongosh.
    • // liquibase formatted mongodb
// changeset authorname:1 runWith:mongosh
  • Liquibase preconditions are not supported.
  • The modifyChangeSets tag is not supported.
  • MongoDB is a NoSQL database, so you cannot use any commands that generate SQL output (such as update-sql and changelog-sync-sql). MongoDB also does not support the database inspection command family (such as diff and generate-changelog). Learn more Liquibase Commands here.
  • Liquibase Pro policy checks have limited support. Database-scoped policy checks are not supported because they are database-specific.
  • OIDC authentication is supported only for MongoDB Atlas. LDAP and Kerberos authentication are not supported for any MongoDB platform. Learn more about MongoDB authentication here: authentication.

Verified database versions

Liquibase MongoDB Pro extension version Liquibase Pro version required MongoDB versions verified MongoDB Shell versions verified Authentication
1.5.0 4.30.0+  
  • MongoDB 5.x, 6.x, 7.x
  • MongoDB Atlas 5, 6, 7
  • AWS DocumentDB 4, 5
  
  • 1.6.x
  • 1.7.x
  • 1.8.x (recommended)
  • SCRAM
  • x.509
  • AWS IAM
  • OIDC
1.4.1 4.28.0+
  • SCRAM
  • x.509
  • AWS IAM
1.4.0
1.3.0 4.24.0+
1.2.0 4.23.1+
  • MongoDB 5.x, 6.x
  • MongoDB Atlas 5, 6
  • AWS DocumentDB 4
1.1.x 4.23.0+
1.0.0 4.20.0–4.21.1
  • MongoDB 5.x, 6.x
  • MongoDB Atlas 5 and 6

Deprecated database versions

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

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

Related links