Formatted Mongo changelog example

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

Tip: 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:

//changeSet Administrator:1 runWith:mongosh 
db = db.getSiblingDB( 'lbcat' );
db.createCollection('person');
//ignoreLines:2
this line will be ignored
this line will be ignored
//changeSet Administrator:2 runWith:mongosh 
db = db.getSiblingDB( 'lbcat' );
db.createCollection('company');
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');
Mongo changelog example

//liquibase formatted mongo

//property name:tableNameProp value:substitutedPropertyCollection

// changeset Administrator:1 runWith:mongosh labels:collections,smoky,smoke
// comment to test
db = db.getSiblingDB( 'lbcat' );
db.createCollection('${tableNameProp}');
//rollback db = db.getSiblingDB( 'lbcat' ); 
//rollback db.substitutedPropertyCollection.drop();

//changeSet Administrator:2 runWith:mongosh labels:collections,smoky,smoke contextFilter:"test,smoke,smokycon" runOnChange:true
db = db.getSiblingDB( 'lbcat' );
db.createCollection('person');