Using Liquibase with MongoDB
MongoDB is a document-oriented NoSQL database. For more information, see MongoDB Documentation.
Supported versions
- 6.X
- 5.X
Note: Liquibase does not work with the MongoDB compatibility features in AWS DocumentDB or Azure Cosmos DB because they use a version of MongoDB that Liquibase does not support.
Prerequisites
- Install Liquibase.
- Create a Liquibase project folder to store all Liquibase files. You can do this manually or with the init project command.
- Create a new Liquibase properties file or use the
liquibase.properties
file included in the installation package. For more information, see Create and Configure a liquibase.properties File.
Install drivers
To use Liquibase and MongoDB, you need four JAR files:
- MongoDB Java Driver Core (
mongodb-driver-core-<version>.jar
) - MongoDB Synchronous Driver (
mongodb-driver-sync-<version>.jar
) - MongoDB BSON (
bson-<version>.jar
) - Liquibase MongoDB extension (
liquibase-mongodb-<version>.jar
)
liquibase/lib
directory.
If you use Maven, pom.xml
file.
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-core</artifactId>
<version>4.9.0</version>
</dependency>
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<version>4.9.0</version>
</dependency>
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>bson</artifactId>
<version>4.9.0</version>
</dependency>
<dependency>
<groupId>org.liquibase.ext</groupId>
<artifactId>liquibase-mongodb</artifactId>
<version>4.20.0</version>
</dependency>
Test your connection
- Ensure your MongoDB database is configured. See Install MongoDB for more information.
- Specify the database URL in the Liquibase properties file. 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:
- Create a text file called changelog (
.xml
) in your project directory and add a changeset. - Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
- Make changes to your database with the update command.
- From a database UI tool, ensure that your database contains
myCollection
along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.
url: mongodb://hostname:27017/myDatabase
Note: 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>

<?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:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
xmlns:pro="http://www.liquibase.org/xml/ns/pro"
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/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">
<changeSet id="1" author="bob">
<ext:createCollection collectionName="myCollection">
<ext:options>
{
validator: {
$jsonSchema: {
bsonType: "object",
required: ["name", "address"],
properties: {
name: {
bsonType: "string",
description: "The Name"
},
address: {
bsonType: "string",
description: "The Address"
}
}
}
},
validationAction: "warn",
validationLevel: "strict"
}
</ext:options>
</ext:createCollection>
</changeSet>
</databaseChangeLog>
liquibase status --username=test --password=test --changelog-file=<changelog.xml>
Note: You can pass arguments in the CLI or keep them in the Liquibase properties file.
liquibase update --changelog-file=<changelog.xml>
Tip: You can use MongoDB Compass to easily view collections in your database. For example, run the commands use myDatabase
and db.myCollection.find()
.

- createCollection creates a collection with the validator.
<changeSet id="1" author="liquibase">
<ext:createCollection collectionName="myCollection">
<ext:options>
{
validator: {
$jsonSchema: {
bsonType: "object",
required: ["name", "address"],
properties: {
name: {
bsonType: "string",
description: "The Name"
},
address: {
bsonType: "string",
description: "The Address"
}
}
}
},
validationAction: "warn",
validationLevel: "strict"
}
</ext:options>
</ext:createCollection>
</changeSet>
- dropCollection removes a collection or view from the database.
<changeSet id="1" author="liquibase">
<ext:dropCollection collectionName="myCollection"/>
</changeSet>
- createIndex creates an index for a collection.
<changeSet id="1" author="liquibase">
<ext:createIndex collectionName="createIndexTest">
<ext:keys>
{ clientId: 1, type: 1}
</ext:keys>
<ext:options>
{unique: true, name: "ui_tppClientId"}
</ext:options>
</ext:createIndex>
<ext:createIndex collectionName="createIndexNoOptionsTest">
<ext:keys>
{ clientId: 1, type: 1}
</ext:keys>
</ext:createIndex>
</changeSet>
- dropIndex drops an index for a collection by keys.
<changeSet id="1" author="liquibase">
<ext:dropIndex collectionName="createIndexTest">
<ext:keys>
{ clientId: 1, type: 1}
</ext:keys>
<ext:options>
{unique: true, name: "ui_tppClientId"}
</ext:options>
</ext:dropIndex>
<ext:dropIndex collectionName="createIndexNoOptionsTest">
<ext:keys>
{ clientId: 1, type: 1}
</ext:keys>
</ext:dropIndex>
</changeSet>
- insertMany inserts multiple documents into a collection.
<changeSet id="1" author="liquibase">
<ext:insertMany collectionName="insertManyTest1">
<ext:documents>
[
{ id: 2 },
{ id: 3,
address: { nr: 1, ap: 5}
}
]
</ext:documents>
</ext:insertMany>
</changeSet>
- insertOne inserts a single document into a collection.
<changeSet id="1" author="liquibase">
<ext:insertOne collectionName="insertOneTest1">
<ext:document>
{
id: 111
}
</ext:document>
</ext:insertOne>
</changeSet>
<changeSet id="2" author="liquibase">
<ext:insertOne collectionName="insertOneTest2">
<ext:document>
{
id: 2
}
</ext:document>
</ext:insertOne>
<ext:insertOne collectionName="insertOneTest3">
<ext:document>
{
id: 3
}
</ext:document>
</ext:insertOne>
</changeSet>
<changeSet id="3" author="liquibase">
<ext:insertOne collectionName="insertOneTest2">
<ext:document>
{
id: 21323123
}
</ext:document>
</ext:insertOne>
<ext:insertOne collectionName="insertOneTest3">
<ext:document>
{
id: 321321313
}
</ext:document>
</ext:insertOne>
</changeSet>
- runCommand provides a helper to run specified database commands. This is the preferred method to issue database commands as it provides a consistent interface between the shell and drivers.
<changeSet id="1" author="liquibase">
<ext:runCommand>
<ext:command>
{ buildInfo: 1 }
</ext:command>
</ext:runCommand>
</changeSet>
<changeSet id="2" author="liquibase">
<ext:adminCommand>
<ext:command>
{ buildInfo: 1 }
</ext:command>
</ext:adminCommand>
</changeSet>
- adminCommand provides a helper to run specified database commands against the admin database.
<changeSet id="2" author="liquibase">
<ext:adminCommand>
<ext:command>
{ buildInfo: 1 }
</ext:command>
</ext:adminCommand>
</changeSet>