MongoDB Pro and Amazon DocumentDB
You can use Liquibase Pro with Amazon DocumentDB, which is a NoSQL database that offers partial MongoDB compatibility. You can use most of the same drivers, application code, and tools in Amazon DocumentDB as you do in MongoDB. There are some functional differences between MongoDB and Amazon DocumentDB, but you can configure your Liquibase project to work with DocumentDB with only a few tweaks.
Amazon DocumentDB emulates the MongoDB API while running over Amazon Aurora on the back-end. Your Amazon DocumentDB database contains one or more clusters containing your database instance. Clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC) environment.
You need a valid Liquibase Pro license key to use Liquibase with Amazon DocumentDB through the MongoDB Pro Extension. If you want to use Liquibase Pro with MongoDB instead of Amazon DocumentDB, see Using Liquibase with the MongoDB Pro Extension.
Verified versions
Amazon DocumentDB versions do not correspond directly to MongoDB versions. Liquibase has been tested on the following Amazon DocumentDB version:
- 4.0
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.
Install drivers
To use Liquibase and Amazon DocumentDB (with MongoDB compatibility), you must download the JAR file that contains the Liquibase MongoDB Pro extension and the JDBC drivers.
liquibase/lib
directory.pom.xml
file.
<dependency>
<groupId>org.liquibase.ext</groupId>
<artifactId>liquibase-commercial-mongodb</artifactId>
<version>1.0.0</version>
</dependency>
Implement Amazon DocumentDB
- Download and Install mongosh if it is not already installed on your machine.
- Download Java 11. The MongoDB Pro Extension requires it.
- Set the
supportsValidator
argument tofalse
in one of the following ways:- Command line:
--supports-validator=false
liquibase.properties
file:liquibase.mongodb.supportsValidator: false
- Environment variable:
LIQUIBASE_MONGODB_SUPPORTS_VALIDATOR=false
- Command line:
- Set the
retryWrites
argument tofalse
in one of the following ways:- Command line:
--retry-writes=false
liquibase.properties
file:liquibase.mongodb.retryWrites: false
- Environment variable:
LIQUIBASE_MONGODB_RETRY_WRITES=false
- JDBC URL:
&retryWrites=false
. See the following section for examples of full URLs.
- Command line:
- (Optional) If you are using TLS/SSL, configure the TLS/SSL encrypted connection for Amazon DocumentDB. For a step-by-step guide, see MongoDB Pro and Amazon DocumentDB TLS/SSL Configuration.
Note: mongosh
is mandatory to use MongoDB with Liquibase Pro and it must be accessible to Liquibase. We recommend that mongosh is in the system PATH
environment variable. If it is not, that location of mongosh must be manually specified in the liquibase.mongosh.conf
file.
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.
Test your connection
- Ensure your Amazon DocumentDB database is configured. For more information, see AWS Documentation: Get Started with Amazon DocumentDB.
- Specify the database URL in the
liquibase.properties
file (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:
TLS on:
url: jdbc:mongodb://localhost:27070/lbcat?tls=true&tlsAllowInvalidHostnames=true&retryWrites=false&tlsCAFile=rds-combined-ca-bundle.pem
TLS off:
url: jdbc:mongodb://localhost:27069/lbcat?tls=false&retryWrites=false
Note: If you set retryWrites
to false
anywhere in your Liquibase project and to true
elsewhere in your project—in the CLI, in your liquibase.properties
file, as an environment variable, in the url
argument, and so on—the value of false
will always take priority, regardless of where you set it.
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 project
command, 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. - XML:
runWith="mongosh"
- YAML:
runWith: mongosh
- JSON:
"runWith": "mongosh"
- 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
myCollection
object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.
In each changeset, you must specify the mongosh
native executor using the runWith
attribute:

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
runWith: mongosh
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
runWith: mongosh
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
runWith: mongosh
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",
"runWith": "mongosh",
"labels": "test_label",
"context": "test_context",
"comment": "test_comment",
"changes": [
{
"createCollection": {
"collectionName": "countries_json"
}
}
]
}
},
{
"changeSet": {
"id": "2",
"author": "as",
"runWith": "mongosh",
"changes": [
{
"dropCollection": {
"collectionName": "towns_json"
}
}
],
"rollback": ""
}
},
---------------------------INSERT ONE--------------------------
{
"changeSet": {
"id": "3",
"author": "as",
"runWith": "mongosh",
"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",
"runWith": "mongosh",
"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",
"runWith": "mongosh",
"changes": [
{
"createIndex": {
"collectionName": "countries_json",
"keys": {
"$rawJson": {
"name": 1,
"type": 1
}
},
"options": {
"$rawJson": {
"unique": true,
"name": "ui_countries_json"
}
}
}
}
]
}
},
{
"changeSet": {
"id": "6",
"author": "as",
"runWith": "mongosh",
"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",
"runWith": "mongosh",
"changes": [
{
"runCommand": {
"command": "{ buildInfo: 1 }"
}
}
],
"rollback": ""
}
},
---------------------------ADMIN COMMAND---------------------------
{
"changeSet": {
"id": "8",
"author": "as",
"runWith": "mongosh",
"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!