What support does Liquibase MongoDB Pro with MongoDB platforms?
Last updated: July 14, 2025
The Liquibase MongoDB Pro extension lets you use all the features of Liquibase Pro with MongoDB, including Policy Checks, Secrets Management, Structured Logging, and MongoDB Pro extension-only commands and access to Drift reports. With this extension, we've also enabled the option to use native MongoDB shell scripts. These features enhance your database's security, reliability, and compatibility with other tools in your development pipeline.
To use the community-maintained Liquibase MongoDB extension, see Contributors Docs: MongoDB Extension.
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 these 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 theinclude
andincludeAll
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
andmongoFile
Change Types. Using these Change Types requires you to specifymongosh
as the value of therunWith
attribute for allmongo
andmongoFile
changesets.
To learn how to specify changes in each format, see Use Native Executors with MongoDB Pro.
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
DATABASECHANGELOGHISTORY table: record a history of all changes made to the database that have been applied and are currently active.
Change Types
You can use many of the standard Liquibase Change Types in MongoDB Pro. MongoDB-specific Change Types include 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 parameters
To configure MongoDB-specific behavior, such as OIDC authentication for MongoDB Atlas, you can set the following Liquibase parameters in the CLI, in flow files, in your liquibase.properties
file, or as environment variables:
mongodb-adjust-tracking-tables-on-startup
mongodb-oidc-authentication-mechanism
mongodb-oidc-environment
mongodb-oidc-oidc-application-id-uri
mongodb-oidc-oidc-client-id
mongodb-retry-writes
mongodb-supports-validator
For more information, see Liquibase Parameters for MongoDB.
Supported commands
MongoDB supports the following commands:
Update commands, except those that generate SQL output. For example:
update
andupdate-count
are supported.Rollback commands, except those that generate SQL output. For example:
rollback
androllback-one-changeset
are supported.Database inspection commands, except
diff-changelog
andgenerate-changelog
. For example:diff
andsnapshot
are supported.
Note: Since MongoDB doesn't have schema objects, Liquibase will return a placeholder schema object in output and in files, which you can ignore. This is because Liquibase’s highest-level objects (catalog, schema) all map to the database object in MongoDB. It is not indicative of an error or problem in your configuration or with the command.
Change tracking commands, except those that generate SQL output. For example:
changelog-sync
,status
, andhistory
are supported.The
connect
command is supported in MongoDB Pro 1.4.0+.Policy checks commands are supported. For example:
checks copy
,checks show
, andchecks run
.All other commands, unless otherwise specified in the Limitations section.
Supported operations reports
Drift Report-- If you're working in an environment that experiences database drift, Liquibase drift reports can alert you of the drift and show you the changes that need to be addressed.
The Drift report is the only report supported for use with the MongoDB Pro extension.
Supported policy checks
You can use changelog-scoped policy checks in MongoDB Pro. For example:
Checks that focus on changeset metadata, such as RollbackRequired and ChangesetLabelCheck.
The generic regex-based check SqlUserDefinedPatternCheck.
Note: These policy checks only work if you have created your own from the regex template. Liquibase uses the java.util.regex engine to match regular expressions.
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:
ChangesetCommentCheck
ChangesetContextCheck
ChangesetLabelCheck
RollbackRequired
RequireChangesetIDisUUID
SqlUserDefinedPatternCheck
Limitations
The child MongoDB scripts referenced by the
include
andincludeAll
tags must contain the changeset decoration and the following minimum changeset metadata:author:id
andrunWith: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
andchangelog-sync-sql
). Learn more: Liquibase CommandsLiquibase 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 authentication is supported for MongoDB Server.
Kerberos authentication is 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.6.0 | 4.32.0+ | 1.6.x 1.7.x 1.8.x (recommended) | SCRAM x.509 AWS IAM OIDC | |
1.5.0 | 4.30.0+ | MongoDB 5.x, 6.x, 7.x, 8.x MongoDB Atlas 5, 6, 7, 8x AWS DocumentDB 4, 5 | ||
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 |
Change history
Change | Version |
Introduced diff, snapshot, include, includeAll, and Drift Report support. | Liquibase Pro 4.32.0+ and MongoDB Pro extension version 1.6.0+ |