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)

Place your JAR file(s) in the liquibase/lib directory. Read more: Adding and Updating Liquibase Drivers.

If you use Maven, you must include the driver JAR as a dependency in your pom.xml file. Read more: Configuring Liquibase Attributes in your Maven POM 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

1. Ensure your MongoDB database is configured. See Install MongoDB for more information.
2. 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:

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>

3. Create a text file called changelog (.xml) in your project directory and add a changeset.
XML example

<?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>

4. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

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.

5. Make changes to your database with the update command.

liquibase update --changelog-file=<changelog.xml>

6. From a database UI tool, ensure that your database contains myCollection along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Tip: You can use MongoDB Compass to easily view collections in your database. For example, run the commands use myDatabase and db.myCollection.find().

Related links

• Liquibase MongoDB Extension
• Liquibase MongoDB Extension Examples
• Liquibase Commands
• Change Types