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 JavaScript files - 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 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:
- 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:
- 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
andupdate-count
are supported. - Rollback commands, except those that generate SQL output. For example,
rollback
androllback-one-changeset
are supported. - 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+.
- The
- Policy checks commands. For example,
copy
,show
, andrun
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:
- 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
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 Liquibase Commands here.Verified database versions
Liquibase MongoDB Pro extension version | Liquibase Pro version required | MongoDB versions verified | MongoDB Shell versions verified | Authentication |
---|---|---|---|---|
1.4.1 | 4.28.0+ |
|
|
|
1.4.0 | ||||
1.3.0 | 4.24.0+ | |||
1.2.0 | 4.23.1+ |
|
||
1.1.x | 4.23.0+ | |||
1.0.0 | 4.20.0–4.21.1 |
|
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