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
- Rollback Considerations - MongoDB operations like
insertOne
andinsertMany
are not automatically reversible. Always plan rollbacks explicitly e.g., by including a corresponding delete or drop changeset if needed. - 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. - 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.
- 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.
- Use runCommand Wisely -
runCommand
is powerful but bypasses Liquibase’s higher-level abstractions. It does not support automatic rollbacks (hence the RollbackImpossibleException).