Using Liquibase with the MongoDB Pro Extension
Note: The MongoDB Pro extension requires Liquibase 4.20+. It is only available to Liquibase Pro users. This extension requires Java 11.
The MongoDB Pro extension streamlines the workflow for MongoDB users. It allows you to use MongoDB's native language in changesets and Change Types. All of this is possible because MongoDB Shell (mongosh) is compatible with Liquibase Pro. MongoDB also supports Targeted Rollback, Flows, and changelog-level quality checks with Liquibase Pro. Learn the details and how to implement this functionality below.
This guide is intended for use with MongoDB products and services provided directly by MongoDB, Inc. This includes MongoDB Atlas, MongoDB Enterprise Server, and MongoDB Community Server. It does not imply support for third-party clones or emulations of Mongo.
Features
Some Liquibase functionality is different with the MongoDB Pro Extension than with other databases:
- As of Liquibase Pro 4.20.1, JSON and YAML changelogs are supported along with the legacy support of XML changelogs.
- MongoDB is a NoSQL database, which means you are unable to use any commands that generate SQL output. Learn more about Liquibase Commands here.
- Rollback commands are supported except for commands that generate SQL output.
- Change tracking commands are supported except for commands that generate SQL output.
- Quality Check functionality that works with the MongoDB Pro Extension is limited to checks targeting the changelog scope. Learn more about Quality Checks here. The pre-packaged Quality Check content currently relevant to MongoDB are these two items:
- Checks that focus on changeset metadata, such as RollbackRequired and ChangesetLabelCheck.
- The generic regex-based check SqlUserDefinedPatternCheck.
Note: These quality checks work only if you have created your own from the regex template. Liquibase uses the java.util.regex engine to match regular expressions.
mongoandmongoFileare the two new Change Types available to Liquibase. They require a user to configure the native executor, Mongo Shell (mongosh), prior to use.
Verified versions
| MongoDB Tested Versions | MongoDB Shell Tested Versions | Liquibase Pro Compatible Version | Supported Auth mechanisms |
|---|---|---|---|
| 4.4.x | 1.6.x 1.7.x 1.8.x - Recommended |
4.19.0 and later | SCRAM & x.509 |
| 5.x | 1.6.x 1.7.x 1.8.x - Recommended |
4.19.0 and later | SCRAM & x.509 |
| 6.x | 1.6.x 1.7.x 1.8.x - Recommended |
4.19.0 and later | SCRAM & x.509 |
Tip: LDAP and Kerberos Authentication are not supported at this time. Learn more about MongoDB Authentication here: authentication
Command support
MongoDB does not support the database inspection commands family or the *sql command variants (such as update-sql and changelog-sync-sql).
Liquibase Pro Quality Checks have limited support. Changelog-scoped quality checks are supported as long as they are not SQL-specific or relational-specific. Database-scoped quality checks are not supported because they are database-specific.
Supported quality checks:
RollbackRequiredChangesetContextCheckChangesetCommentCheckChangesetLabelCheckRequiredChangesetDisUUIDSqlUserDefinedPatternCheck
Verification level
Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Open Source and Liquibase Pro. For more information, see Database Verification Levels.
Foundational: Database has been tested and validated to deliver the basic functionality of change management and change tracking aligned with the database. Some additional advanced capabilities may be implemented. The Liquibase customer support team provides how-to/usage support around verified capabilities for commercial customers.
Prerequisites
- Introduction to Liquibase – Dive into Liquibase concepts.
- Install Liquibase – Download Liquibase on your machine.
- Get Started with Liquibase – Learn how to use Liquibase with an example database.
- Design Your Liquibase Project – Create a new Liquibase project folder and organize your changelogs
- How to Apply Your Liquibase Pro License Key – If you use Liquibase Pro, activate your license.
Implement the MongoDB Pro extension
- If you have the current open source MongoDB version installed, remove it and the associated drivers from your machine.
- Ensure that your MongoDB Pro Extension User Roles are established before continuing.
- Download and Install mongosh if it is not already installed on your machine.
Tip: We suggest that you add mongosh to the system
PATHenvironment variable.Note:
mongoshis mandatory to use MongoDB with Liquibase Pro and it must be accessible to Liquibase. We recommend that mongosh is in the systemPATHenvironment variable. If it is not, that location of mongosh must be manually specified in theliquibase.mongosh.conffile. -
Download Java 11, this extension requires it.
Tip: Java 11 may already be present on your machine if you used the installer to install Liquibase. We recommend installing Liquibase with Java 11 with the installer asset available on GitHub.
- Download the JAR file that contains the MongoDB Pro Extension and drivers from Maven Central.
Note: If you are a Maven user, do not download the MongoDB Pro Extension JAR file. You only need to specify the dependency listed below in your
pom.xmlfile and all required artifacts will download by Maven.<dependency> <groupId>org.liquibase.ext</groupId> <artifactId>liquibase-commercial-mongodb</artifactId> <version>1.0.0</version> </dependency> - Extract the single
liquibase-commercial-mongodb-1.0.0.jarfile and place it in theliquibase/libdirectory. - Apply your Liquibase Pro key. See How to Apply Your Liquibase Pro License Key
Configure your TLS/SSL encrypted connection
If you are using TLS/SSL, configure the TLS/SSL encrypted connection for the MongoDB Pro extension.
Tip: This is only required if you are using SSL/TLS because it is active on your Mongo server or because you are using MongoDB Atlas.
- Configure the MongoDB instance by first following Mongo's configuration guide.
- Then verify that it works by following Mongo's verification guide.
- Add the
--tlsCertificateKeyFilecertificate that is produced in the configuration step above to the Java keystore. The--tlsCertificateKeyFilespecifies the.pemfile that contains mongosh's certificate. -
Add the
urlparameter to the CLI, liquibase.properties file, or set it as an environment variable:Example: liquibase.properties file:
liquibase.command.url=mongodb+srv://<hostname>/<database>liquibase.command.url: mongodb://localhost:27017/lbcat?tls=true&tlsCAFile=mongodb.pem
Environment variable:LIQUIBASE_COMMAND_URL=mongodb+srv://<hostname>/<database>LIQUIBASE_COMMAND_URL: mongodb://localhost:27017/lbcat?tls=true&tlsCAFile=mongodb.pemIf you are using a Java keystore that is not the default, you must add the necessary environment variables before running Liquibase commands.
On Linux:
export JAVA_OPTS="-Djavax.net.ssl.keyStore=PATH_TO_KEYSTORE/cacerts -Djavax.net.ssl.keyStorePassword=PASSWORD"On Windows:
set JAVA_OPTS=-Djavax.net.ssl.keyStore="PATH_TO_KEYSTORE\\cacerts" -Djavax.net.ssl.keyStorePassword=PASSWORDDo not use
setxas it addskeyStorePasswordto system environment variables.
On Linux:
sudo keytool -importcert -trustcacerts -file PATH_TO_CERT_FILE/mongodb-cert.crt -cacerts -storepass changeit -alias MongoDBOn Windows, open terminal in Administrator mode and run:
keytool -importcert -trustcacerts -file PATH_TO_CERT_FILE\\mongodb-cert.crt -cacerts -storepass changeit -alias mongodbNote: The default password for keystore is changeit.
Troubleshooting errors
After connecting Liquibase with the MongoDB Pro Extension, you may come across an error that states:
Error: Could not find or load main class Files\\Java\\{jdk-version}.security.cacerts Caused by: java.lang.ClassNotFoundException: Files\\Java\\{jdk-version}.security.cacertsThis means that Liquibase Pro is struggling to find the certification file. To resolve the issue, run the following command in the CLI:
On Windows:
set JAVA_OPTS=-Djavax.net.ssl.keyStore="%JAVA_HOME%\\lib\\security\\cacerts"On Linux:
export JAVA_OPTS=-Djavax.net.ssl.keyStore=$JAVA_HOME/lib/security/cacertsTest your connection
- Ensure your MongoDB database is configured. See Install MongoDB for more information.
- Specify the database URL in the
liquibase.propertiesfile (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 JDBC format:
url: mongodb://hostname:27017/myDatabaseNote: If you are unsure about how to configure the url property, refer to Connection String URI Format.
Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: licenseKey: <paste code here>
-
Create a text file called changelog (
.xml) in your project directory and add a changeset.If you already created a changelog using the
init projectcommand, you can use that instead of creating a new file. When adding onto an existing changelog, be sure to only add the changeset and to not duplicate the changelog header. - Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
- Then make changes to your database with the update command:
- From a database UI tool, ensure that your database contains the
myCollectionobject you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.
Note: The use of JSON and YAML changelogs is available in Liquibase Pro MongoDB commercial version 1.0.0.
XML example
The Liquibase MongoDB Pro extension uses a unique mongodb-pro XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mongodb-pro="http://www.liquibase.org/xml/ns/pro-mongodb"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
http://www.liquibase.org/xml/ns/pro-mongodb http://www.liquibase.org/xml/ns/pro-mongodb/liquibase-pro-mongodb-latest.xsd">
<changeSet id="1" author="nvoxland" runWith="mongosh">
<mongodb-pro:mongo>
db = db.getSiblingDB( 'mydb' );
db.createCollection('person2');
</mongodb-pro:mongo>
<rollback>
<mongodb-pro:mongo>
db = db.getSiblingDB( 'mydb' );
db.person2.drop();
</mongodb-pro:mongo>
</rollback>
</changeSet>
<changeSet id="2" author="nvoxland" runWith="mongosh">
<mongodb-pro:mongoFile path="scriptFile.js" relativeToChangelogFile="true"/>
<rollback>
<mongodb-pro:mongoFile path="scriptFile-rollback.js" relativeToChangelogFile="true"/>
</rollback>
</changeSet>
<changeSet id="3" author="nvoxland" runWith="mongosh">
<mongodb-pro:mongo>
db.products.insertMany( [
{ item: "card", qty: 15 },
{ item: "envelope", qty: 20 },
{ item: "stamps" , qty: 30 }
] );
</mongodb-pro:mongo>
<rollback>
<mongodb-pro:mongo>
db.products.deleteMany( { } );
</mongodb-pro:mongo>
</rollback>
</changeSet>
</databaseChangeLog>databaseChangeLog:
- changeSet:
id: 1
author: your.name
labels: example-label
context: example-context
comment: example-comment
changes:
- createTable:
tableName: person
columns:
- column:
name: id
type: int
autoIncrement: true
constraints:
primaryKey: true
nullable: false
- column:
name: name
type: varchar(50)
constraints:
nullable: false
- column:
name: address1
type: varchar(50)
- column:
name: address2
type: varchar(50)
- column:
name: city
type: varchar(30)
- changeSet:
id: 2
author: your.name
labels: example-label
context: example-context
comment: example-comment
changes:
- createTable:
tableName: company
columns:
- column:
name: id
type: int
autoIncrement: true
constraints:
primaryKey: true
nullable: false
- column:
name: name
type: varchar(50)
constraints:
nullable: false
- column:
name: address1
type: varchar(50)
- column:
name: address2
type: varchar(50)
- column:
name: city
type: varchar(30)
- changeSet:
id: 3
author: other.dev
labels: example-label
context: example-context
comment: example-comment
changes:
- addColumn:
tableName: person
columns:
- column:
name: country
type: varchar(2){
"databaseChangeLog": [
---------------------------CREATE AND DROP COLLECTION---------------------------
{
"changeSet": {
"id": "1",
"author": "as",
"labels": "test_label",
"context": "test_context",
"comment": "test_comment",
"changes": [
{
"createCollection": {
"collectionName": "countries_json"
}
}
]
}
},
{
"changeSet": {
"id": "2",
"author": "as",
"changes": [
{
"dropCollection": {
"collectionName": "towns_json"
}
}
],
"rollback": ""
}
},
---------------------------INSERT ONE--------------------------
{
"changeSet": {
"id": "3",
"author": "as",
"changes": [
{
"insertOne": {
"collectionName": "towns_json",
"document": {
"$rawJson": {
"name": "New York",
"population": 222000000,
"famousFor": [
"the MOMA",
"food",
"Derek Jeter"
],
"mayor": {
"name": "Bill de Blasio",
"party": "D"
}
}
}
}
}
],
"rollback": ""
}
},
---------------------------INSERT MANY-------------------------
{
"changeSet": {
"id": "4",
"author": "as",
"changes": [
{
"insertMany": {
"collectionName": "countries_json",
"documents": {
"$rawJson": [
{
"_id": "us",
"name": "United States",
"exports": {
"foods": [
{
"name": "bacon",
"tasty": "true"
},
{
"name": "burger"
}
]
}
},
{
"_id": "ca",
"name": "Canada",
"exports": {
"foods": [
{
"name": "bacon",
"tasty": false
},
{
"name": "syrup",
"tasty": true
}
]
}
},
{
"_id": "mx",
"name": "Mexico",
"exports": {
"foods": [
{
"name": "salsa",
"tasty": true,
"condiment": true
}
]
}
}
]
}
}
}
],
"rollback": {
"runCommand": {
"command": "{ delete: \"countries_json\", deletes: [{q: { }, limit: 0}] }"
}
}
}
},
---------------------------CREATE AND DROP INDEX---------------------------
{
"changeSet": {
"id": "5",
"author": "as",
"changes": [
{
"createIndex": {
"collectionName": "countries_json",
"keys": {
"$rawJson": {
"name": 1,
"type": 1
}
},
"options": {
"$rawJson": {
"unique": true,
"name": "ui_countries_json"
}
}
}
}
]
}
},
{
"changeSet": {
"id": "6",
"author": "as",
"changes": [
{
"dropIndex": {
"collectionName": "countries_json",
"keys": {
"$rawJson": {
"name": 1,
"type": 1
}
},
"options": {
"$rawJson": {
"unique": true,
"name": "ui_countries_json"
}
}
}
}
]
}
},
---------------------------RUN COMMAND---------------------------
{
"changeSet": {
"id": "7",
"author": "as",
"changes": [
{
"runCommand": {
"command": "{ buildInfo: 1 }"
}
}
],
"rollback": ""
}
},
---------------------------ADMIN COMMAND---------------------------
{
"changeSet": {
"id": "8",
"author": "as",
"changes": [
{
"adminCommand": {
"command": "{ buildInfo: 1 }"
}
}
],
"rollback": ""
}
}
]
}liquibase status --username=test --password=test --changelog-file=<changelog.xml>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_jdbc_url>
Liquibase command 'status' was executed successfully.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.Tip: You can use MongoDB Compass to easily view collections in your database. For example, run the commands use myDatabase and db.myCollection.find().
Now you're ready to start making deployments with Liquibase!