Concept
Version · 5.2.2
User guide

Formatted Mongo changelog example

Last updated: August 12, 2026

Liquibase supports Changelog files in that are formatted for Mongo. These changelog files use mongosh methods. Although these methods use JavaScript-like syntax and have .js file extensions, they are written in a specialized language designed for interacting with MongoDB, not standard JavaScript. Like other file types, you can use as many formatted Mongo changelogs as your database needs.

Formatted Mongo files use comments to provide Liquibase with metadata. Each Mongo file must begin with the following comment:

//liquibase formatted mongo

include and includeAll

In Liquibase Secure 4.32.0 and later, you can use the include or includeAll tags in a formatted Mongo root changelog to reference other changelog files. This feature is not available in Liquibase 4.27.0 and earlier.

You can reference formatted Mongo changelogs from XML, YAML, and JSON root changelogs in all versions of Liquibase Secure and Liquibase Open Source. This allows you to make a Mongo changelog the parent of any additional changelog files.

changeset

Each changeset in a formatted Mongo file begins with a comment of the form:

//changeset author:id attribute1:value1 attribute2:value2 [...]

changeset attributes

Use the following attributes for your changesets:

Note: The runWith attribute is mandatory for Formatted Mongo.

Attribute	Description
`context`	Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets will be executed in any particular migration run.
`dbms`	Specifies which database type(s)a changeset is to be used for. See valid database type names on `dbms`. Separate multiple databases with commas. Specify that a changeset is not applicable to a particular database type by prefixing with `!`.The keywords `all` and `none` are also available.
`failOnError`	Defines whether a database migration will fail if an error occurs while executing the changeset. Default: `true`.
`ignore`	Tells Liquibase to treat a particular changeset as if it does not exist. Default: `false`. Since 3.6 (XML/YAML/JSON). Since 4.19.0 (SQL).
`labels`	Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run.
`logicalFilePath`	Overrides the file name and path when creating the unique identifier of changesets. It is required when you want to move or rename changelogs.
`runAlways`	Executes the changeset on every run, even if it has been run before. Default: `false`.
`runOnChange`	Executes the changeset when you create it and each time it changes. Default: `false`.
`runWith`	Mandatory. Specifies a native executor to run your Mongo code (`jdbc`, `mongosh`, `psql`, `sqlcmd`, `sqlpus`, or a custom executor). Default: `jdbc`.

Rollback actions

Specify Mongo with rollback

Your changesets may include statements to be applied when rolling back the changeset. Rollback statements have the following format:

//rollback db = db.getSiblingDB( 'lbcat' ); //rollback db.substitutedPropertyCollection.drop();

Comment

The comment is a description of the changeset.

Note: By default, the statements will be split on a ‘;' or ‘go' at the end of lines.

Future releases of Liquibase may use comments to generate documentation.

// comment: some comment

Note: When you add a comment to your changeset and deploy this changeset, the comment will not be applied to the DATABASECHANGELOG tracking table.

You can also add Mongo comments outside changesets using the format // my comment.

Valid checksum

Valid checksum is a checksum which is valid for a specific changeset, regardless of what is stored in the database. It is typically used when you need to change a changeset and don't want errors to be thrown on databases on which it has been already run. Nevertheless, it is not a recommended procedure. Since 3.5

--validCheckSum: 3:098f6bcd4621d373cade4e832627b4f6 --validCheckSum: 7:ad0234829205b9033196ba818f7a872b

Ignore lines

The ignoreLines attribute allows you to ignore specific lines within a changeset. This is similar to the ignore attribute (see the changeset attributes section), but the scope can be more precise. ignoreLines is typically used when you run the same script with other Mongo tools. Since 3.7

Mark two lines to ignore using the start-end syntax

//changeSet Administrator:1 runWith:mongosh  
db = db.getSiblingDB( 'lbcat' );
db.createCollection('person'); 

//ignoreLines:start
this line will be ignored
this line will be ignored
//ignoreLines:end

//changeSet Administrator:2 runWith:mongosh
db = db.getSiblingDB( 'lbcat' );
db.createCollection('company');

Schema validation

MongoDB collections accept documents of any shape by default. To require a structure, pass a validator with a $jsonSchema expression when you create the collection. Liquibase deploys the validator as part of the changeset, so the rule is version-controlled and tracked like any other change.

Note: Liquibase Secure also ships policy checks that enforce this. See collectionMustHaveValidator and mongoCrCollectionValidatorChk.

Create a collection with a jsonSchema validator

//liquibase formatted mongo

//changeset your.name:1 runWith:mongosh
db = db.getSiblingDB( 'lbcat' );
db.createCollection( 'students', {
    validator: {
        $jsonSchema: {
            bsonType: 'object',
            title: 'Student Document Validation',
            required: [ 'name', 'year', 'major' ],
            properties: {
                name: {
                    bsonType: 'string',
                    description: 'name must be a string and is required'
                },
                year: {
                    bsonType: 'int',
                    minimum: 2017,
                    maximum: 3017,
                    description: 'year must be an integer between 2017 and 3017 and is required'
                },
                major: {
                    enum: [ 'Math', 'English', 'Computer Science', 'History' ],
                    description: 'can only be one of the enum values and is required'
                }
            }
        }
    }
} );
//rollback db = db.getSiblingDB( 'lbcat' );
//rollback db.students.drop();