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 Quality 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 JavaScript – Let developers use Liquibase without modifying existing scripts - Formatted Mongo changelogs (MongoDB Pro 1.3.0+) – Add Liquibase changeset metadata to your
mongosh
scripts to use features like rollback, contexts, labels, and theinclude
andincludeAll
tags - XML, YAML, and JSON modeled changelogs – Specify
mongosh
scripts using themongo
andmongoFile
Change Types and create root changelogs to useinclude
andincludeAll
To learn how to specify changes in each format, see Using mongosh in Your Changelog.
Getting started tutorials
To learn how to configure the Liquibase MongoDB Pro extension with your installation of MongoDB, see the following topics:
- Using Liquibase MongoDB Pro with MongoDB Atlas – Multi-cloud database service to manage databases on demand
- Using Liquibase MongoDB Pro with MongoDB Community and Enterprise Server – Fully-featured MongoDB products for small or large-scale development
- Using Liquibase MongoDB Pro with Amazon DocumentDB – Use MongoDB functionality through a clone, Amazon DocumentDB
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:
- Quality 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
- Flow Files – Create repeatable, portable, and platform-independent Liquibase workflows to run in any of your CI/CD tools
- Feature Flags – Define and control when database changes are applied
- 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 all 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.
Supported commands
MongoDB supports the following commands:
- Update commands, except those that generate SQL output. For example,
update
andupdate-count
. - Rollback commands, except those that generate SQL output. For example,
rollback
androllback-one-changeset
. - Change tracking commands, except those that generate SQL output. For example,
changelog-sync
,status
, andhistory
. - Quality checks commands. For example,
copy
,show
, andrun
. - All other commands, unless otherwise specified in the Limitations section.
For more information, see About Liquibase Commands.
Supported quality checks
You can use changelog-scoped quality 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 quality 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 quality checks are supported as long as they are not SQL-specific or relational-specific. The following is a full list of quality checks supported on MongoDB:
ChangesetCommentCheck
ChangesetContextCheck
ChangesetLabelCheck
RollbackRequired
RequireChangesetDisUUID
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
modifyChangeSets
tag is not supported.update-sql
and changelog-sync-sql
). MongoDB also does not support the database inspection command family (such as diff
and generate-changelog
). Learn more About Liquibase Commands here.Verified versions
Liquibase MongoDB Pro extension version | Liquibase Pro version required | MongoDB versions verified | MongoDB Shell versions verified | Authentication |
---|---|---|---|---|
1.3.X | 4.24.0+ |
|
|
|
1.2.X | 4.23.0+ |
|
||
1.1.X | 4.19.0–4.21.1 | |||
1.0.X |
|
Deprecated versions
MongoDB 4.4.x is deprecated as of February 29, 2024
MongoDB Atlas 4.4.x is deprecated as of February 29, 2024