Liquibase MongoDB Basic Commands Reference

This guide provides examples of commonly used Liquibase MongoDB changesets, including collection management, indexing, document operations, and custom run commands. For end-to-end guidance, see Generate MongoDB Changelog and MongoDB Changelog Example.

Collection Operations

Manage MongoDB collections with changesets.

Create Collection

- changeSet:
    id: create-collection-1
    author: devteam@company.com
    changes:
      - createCollection:
          collectionName: users

Drop Collection

- changeSet:
    id: drop-collection-1
    author: devteam@company.com
    changes:
      - dropCollection:
          collectionName: users

Index Operations

Define and manage indexes for optimized query performance.

Create Index

- changeSet:
    id: create-index-1
    author: devteam@company.com
    changes:
      - createIndex:
          collectionName: users
          keys: '{email: 1}'
          options: '{unique: true, name: "idx_email_unique"}'

Drop Index

- changeSet:
    id: drop-index-1
    author: devteam@company.com
    changes:
      - dropIndex:
          collectionName: users
          keys: '{email: 1}'

Document Operations

Insert or manage documents directly in MongoDB collections.

Insert One Document

- changeSet:
    id: insert-user-1
    author: devteam@company.com
    changes:
      - insertOne:
          collectionName: users
          document: >
            {
              "name": "John Doe",
              "email": "john@example.com",
              "age": 30
            }

Insert Many Documents

- changeSet:
    id: insert-users-bulk
    author: devteam@company.com
    changes:
      - insertMany:
          collectionName: users
          documents: >
            [
              {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25
              },
              {
                "name": "Bob Johnson",
                "email": "bob@example.com",
                "age": 35
              }
            ]

Generic Run Command

Execute raw MongoDB commands when no direct Liquibase abstraction exists.

Basic Run Command

- changeSet:
    id: run-command-1
    author: devteam@company.com
    changes:
      - runCommand:
          command: >
            {
              "createIndexes": "users",
              "indexes": [
                {
                  "key": {"name": 1},
                  "name": "idx_name"
                }
              ]
            }

Run Command with Validation

- changeSet:
    id: add-validation-schema
    author: devteam@company.com
    changes:
      - runCommand:
          command: >
            {
              "collMod": "users",
              "validator": {
                "$jsonSchema": {
                  "bsonType": "object",
                  "required": ["name", "email"],
                  "properties": {
                    "name": {"bsonType": "string"},
                    "email": {"bsonType": "string"}
                  }
                }
              }
            }

Complete Example Changelog

A full example demonstrating collections, indexes, inserts, and schema validation.

databaseChangeLog:
  - changeSet:
      id: devteam:1
      author: devteam@company.com
      comment: Create users collection
      changes:
        - createCollection:
            collectionName: users
      
  - changeSet:
      id: devteam:2
      author: devteam@company.com
      comment: Create indexes
      changes:
        - createIndex:
            collectionName: users
            keys: '{name: 1}'
            options: '{name: "idx_name"}'
        - createIndex:
            collectionName: users
            keys: '{email: 1}'
            options: '{unique: true, name: "idx_email_unique"}'

  - changeSet:
      id: devteam:3
      author: devteam@company.com
      comment: Insert initial data
      changes:
        - insertOne:
            collectionName: users
            document: >
              {
                "name": "John Doe",
                "age": 30,
                "email": "john@example.com"
              }

  - changeSet:
      id: devteam:4
      author: devteam@company.com
      comment: Add validation using runCommand
      changes:
        - runCommand:
            command: >
              {
                "collMod": "users",
                "validator": {
                  "$jsonSchema": {
                    "bsonType": "object",
                    "required": ["name", "email"],
                    "properties": {
                      "name": {"bsonType": "string"},
                      "email": {"bsonType": "string"}
                    }
                  }
                }
              }

Admin Command

Use adminCommand for database-level administrative operations such as retrieving server status, listing databases, or renaming collections. This change maps directly to the MongoDB db.adminCommand method and is backed by liquibase.ext.mongodb.change.AdminCommandChange. Unlike runCommand, which executes in the current database context, db.adminCommand() always runs against the admin database, regardless of where it is invoked.

- changeSet:
    id: admin-command-rename-collection
    author: devteam@company.com
    changes:
      - adminCommand:
          command: >
            {
              "renameCollection": "test.orders",
              "to": "test.orders-2016"
            }

Best Practices & Usage Notes

1. Rollback Considerations - MongoDB operations like insertOne and insertMany are not automatically reversible. Always plan rollbacks explicitly e.g., by including a corresponding delete or drop changeset if needed.
2. Index Naming Conventions - Use clear, descriptive index names (idx_email_unique, idx_name) to avoid collisions and simplify debugging. MongoDB auto-generates index names if not provided, which can make schema management inconsistent across environments.
3. Idempotency - Liquibase tracks applied changesets by ID and author. Re-running the same changelog will not re-apply changes, which makes migrations safer across multiple environments. Ensure your changeset IDs remain unique and descriptive.
4. Environment-Specific Data - Avoid inserting environment-specific data (like test users or secrets) directly in production changelogs. Instead, use Liquibase contexts to conditionally run certain changesets.
5. Use runCommand Wisely - runCommand is powerful but bypasses Liquibase’s higher-level abstractions. It does not support automatic rollbacks (hence the RollbackImpossibleException).