Skip to content
Star Us On GitHub

Use Liquibase with MongoDB

MongoDB is a document-oriented NoSQL database. For more information, see the MongoDB Documentation.

Supported database versions

Note

This community-maintained MongoDB extension supports the MongoDB change types shown in the MongoDB command examples section at the bottom of this page.

If you need complete MongoDB support, please use the MongoDB “mongosh” implementation as described in AWS DocumentDB and the MongoDB Pro extension.

If you are looking for information on CosmosDB support, it can be found here: Using Liquibase with Azure CosmosDB.

Prerequisites

Install drivers

All Users

  1. Download the following four JAR files:

  2. Place the JAR file(s) in the liquibase/lib directory.

Maven Users (additional step)

If you use Maven, you must also include the driver JAR as a dependency in your pom.xml file using the following code.

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-core</artifactId>
    <version>[4.11.1,)</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>[4.11.1,)</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson</artifactId>
    <version>[4.11.1,)</version>
</dependency>
<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-mongodb</artifactId>
    <version>[4.24.0,)</version>
</dependency>

Database connection

Configure connection

  1. Ensure your MongoDB database is configured. See Install MongoDB for more information.

  2. 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:

    url: mongodb://<hostname>:27017/<database_name>

    Note

    If you are unsure about how to configure the url property, refer to the Connection String URI Format.

  3. (optional) Enable Liquibase Pro capabilities

    To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file:

    liquibase.licenseKey: <paste key here>

Test connection

  1. Create a text file called changelog in your project directory and add a changeset.

    Note

    The use of JSON and YAML changelogs is available as of Liquibase version 4.20

    <?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="http://www.liquibase.org/xml/ns/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/mongodb
         http://www.liquibase.org/xml/ns/mongodb/liquibase-mongodb-latest.xsd">

  <changeSet id="1" author="your_name" labels="createCollectionLabel" context="createCollectionContext">
    <comment>create_collection_comment</comment>
    <mongodb:createCollection collectionName="towns_xml"/>
  </changeSet>
</databaseChangeLog>

    databaseChangeLog:
  - changeSet:
      id: 2
      author: your_name
      labels: createCollectionLabel
      context: createCollectionContext
      comment: create_collection_comment
      changes:
        - createCollection:
          collectionName: towns_yaml

    {
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "3",
        "author": "your_name",
        "labels": "createCollectionLabel",
        "context": "createCollectionContext",
        "comment": "create_collection_comment",
        "changes": [
          {
            "createCollection": {
              "collectionName": "towns_json"
            }
          }
        ]
      }
    }
  ]
}

  2. 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.

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

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

  4. 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().

MongoDB command examples

Changelog Template

The MongoDB command examples below assume this default XML changelog.

<?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="http://www.liquibase.org/xml/ns/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/mongodb
         http://www.liquibase.org/xml/ns/mongodb/liquibase-mongodb-latest.xsd">

  <!-- Changesets from the examples below go here -->

</databaseChangeLog>

MongoDB Commands

createCollection

Create a collection with the validator. 

<changeSet id="1" author="liquibase">
  <mongodb:createCollection collectionName="myCollection">
    <mongodb: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"
      }
    </mongodb:options>
  </mongodb:createCollection>
</changeSet>

dropCollection

Remove a collection or view from the database. 

<changeSet id="1" author="liquibase">
  <mongodb:dropCollection collectionName="myCollection"/>
</changeSet>

createIndex

Create an index for a collection. 

<changeSet id="1" author="liquibase">
  <mongodb:createIndex collectionName="createIndexTest">
    <mongodb:keys>
      { clientId: 1, type: 1}
    </mongodb:keys>
    <mongodb:options>
      {unique: true, name: "ui_tppClientId"}
    </mongodb:options>
  </mongodb:createIndex>
</changeSet>

dropIndex

Drop an index for a collection by keys. 

<changeSet id="1" author="liquibase">
  <mongodb:dropIndex collectionName="createIndexTest">
    <mongodb:keys>
      { clientId: 1, type: 1}
    </mongodb:keys>
  </mongodb:dropIndex>
</changeSet>

insertMany

Insert multiple documents into a collection. 

<changeSet id="1" author="liquibase">
  <mongodb:insertMany collectionName="insertManyTest1">
    <mongodb:documents>
      [
        { id: 2 },
        { id: 3,
          address: { nr: 1, ap: 5}
        }
      ]
    </mongodb:documents>
  </mongodb:insertMany>
</changeSet>

insertOne

Insert a single document into a collection. 

<changeSet id="1" author="liquibase">
  <mongodb:insertOne collectionName="insertOneTest1">
    <mongodb:document>
      {
        id: 111
      }
    </mongodb:document>
  </mongodb:insertOne>
</changeSet>

<changeSet id="2" author="liquibase">
  <mongodb:insertOne collectionName="insertOneTest2">
    <mongodb:document>
      {
        id: 2
      }
    </mongodb:document>
  </mongodb:insertOne>
</changeSet>

runCommand

Provide 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">
  <mongodb:runCommand>
    <mongodb:command>
      { buildInfo: 1 }
    </mongodb:command>
  </mongodb:runCommand>
</changeSet>

adminCommand

Provide a helper to run specified database commands against the admin database. 

<changeSet id="2" author="liquibase">
  <mongodb:adminCommand>
    <mongodb:command>
      { buildInfo: 1 }
    </mongodb:command>
  </mongodb:adminCommand>
</changeSet>