Use Native Executors with MongoDB Pro

This page describes how to use Liquibase with the Mongosh native executor on a MongoDB Pro database.

Prerequisites

Use Liquibase 4.20.0 or later.
Add Mongosh to your PATH environment variable. Alternatively, pass its location in the liquibase.mongosh.conf file or from the command prompt during runtime. See liquibase.mongosh.path in the Mongosh integration arguments section.

Note: Liquibase searches the executor location in the following order: runtime arguments, .conf file values, and then your PATH.

Setup

Add the runWith attribute to the needed changesets in the changelog:

SQL: runWith:mongosh
XML: runWith="mongosh"
YAML: runWith: mongosh
JSON: "runWith": "mongosh"

Tip: For more information, see the runWith and mongosh examples section.

Specify the Mongosh integration arguments in one of the following ways:

Pass the values at runtime on the command line
Add the values to liquibase.mongosh.conf or the Liquibase properties file.
Set the values as environment variables
Run the values as Java system properties (JAVA_OPTS) along with any command at the command prompt:

Windows

set JAVA_OPTS=-Dliquibase.mongosh.<option>=<value> && liquibase <command> --changelog-file=my_script.js

macOS/Linux

export JAVA_OPTS=-Dliquibase.mongosh.<option>=<value> && liquibase <command> --changelog-file=my_script.js

Run a Liquibase command:

Example: liquibase status --changelog-file=my_script.js

Note: If the command fails, you will receive an error message. However, if you add a property that is not used in Liquibase to the liquibase.mongosh.conf file, no error occurs. Liquibase only ignores it.

Using `runWith` in your changelogs

In Liquibase, you organize changes into one or more changelogs. Your changelogs contain individual changes to your database.

You can write Liquibase changelogs in the MongoDB Pro extension in three ways:

Native MongoDB Shell (mongosh) scripts in MongoDB Query Language (MQL): let developers use Liquibase without modifying existing MQL scripts, which may be JavaScript (.js) files.
Formatted Mongo changelogs (MongoDB Pro 1.3.0+): add Liquibase changeset metadata to your MQL scripts to use features like rollback, contexts, labels, and the include and includeAll tags. These must be saved as .js files.
YAML, JSON, and XML modeled changelogs: specify changes for Liquibase to deploy without the need for MQL scripts. However, you can still deploy MQL scripts in YAML, JSON, and XML changelogs by using the mongo and mongoFile Change Types. Using these Change Types requires you to specify mongosh as the value of the runWith attribute for all mongo and mongoFile changesets.

Native MongoD Shell (`mongosh`) scripts

The MongoDB Pro extension lets you use MongoDB's native language of MongoDB Query Language (MQL), which you may be storing in JavaScript files, in Liquibase changesets and Change Types. This is possible because MongoDB Shell (mongosh) is compatible with Liquibase Pro. For more information, see MongoDB: Write Scripts. Example syntax:

db.createCollection('customers');

`runWith` and `mongosh` examples

Formatted Mongo changelogs

With the Liquibase MongoDB Pro extension 1.3.0+, you can use a formatted Mongo changelog for MongoDB Pro, similar to a formatted SQL changelog. This lets you use mongosh scripts written in MongoDB Query Language (MQL) directly in Liquibase while also having access to all Liquibase features.

All Liquibase formatted Mongo changelogs must use the file extension .JS or .js (JavaScript). They must also begin with a changelog header: // liquibase formatted mongodb. Your changesets must each specify runWith:mongosh. For example:

// liquibase formatted mongodb

// changeset your.name:1 labels:example-label context:example-context runWith:mongosh
// comment: example comment

db.createCollection('customers');

// rollback db = db.person.drop()

XML, YAML, and JSON changelogs

db.createCollection('customers');

// liquibase formatted mongodb

// changeset your.name:1 labels:example-label context:example-context runWith:mongosh
// comment: example comment

db.createCollection('customers');

// rollback db = db.person.drop()

databaseChangeLog:
  - changeSet:
      id: 1
      author: your.name
      runWith: mongosh
      changes:
        - mongo:
            mongo: "db.createCollection('person')"
            dbms: mongodb
        - rollback:
            mongo:
              mongo: "db.person.drop()"

  - changeSet:
      id: 2
      author: your.name
      runWith: mongosh
      changes:
        - mongoFile:
            path: "scriptFile.txt"
            dbms: mongodb
            relativeToChangelogFile: "true"
        - rollback:
            mongo:
              mongo: "db.company.drop()"

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "your.name",
        "runWith": "mongosh",
        "changes": [
          {
            "mongo": {
              "dbms": "mongodb",
              "mongo": "db.createCollection('person')"
            }
          }
        ],
        "rollback": [
          {
            "mongo": {
              "mongo": "db.person.drop()"
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "2",
        "author": "your.name",
        "runWith": "mongosh",
        "changes": [
          {
            "mongoFile": {
              "dbms": "mongodb",
              "path": "scriptFile.txt",
              "relativeToChangelogFile": true
            }
          }
        ],
        "rollback": [
          {
            "mongo": {
              "mongo": "db.company.drop()"
            }
          }
        ]
      }
    }
  ]
}

The Liquibase MongoDB Pro extension uses a unique mongodb-pro XML namespace and XSD files in the changelog header. However, the ext prefix used with other extensions is backwards-compatible:

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:mongodb-pro="http://www.liquibase.org/xml/ns/pro-mongodb"
    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/pro-mongodb http://www.liquibase.org/xml/ns/pro-mongodb/liquibase-pro-mongodb-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" runWith="mongosh">
        <mongodb-pro:mongo dbms="mongodb">
            db.createCollection('person')
        </mongodb-pro:mongo>

        <rollback>
            <mongodb-pro:mongo>
                db.person.drop()
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>

    <changeSet id="2" author="your.name" runWith="mongosh">
        <mongodb-pro:mongoFile dbms="mongodb" path="scriptFile.txt" relativeToChangelogFile="true"/>

        <rollback>
            <mongodb-pro:mongo>
                db.company.drop()
            </mongodb-pro:mongo>
        </rollback>
    </changeSet>

</databaseChangeLog>

Tip: The preceding examples show only the mongo and mongoFile Change Types for Liquibase Pro. For a list of all Liquibase Pro and Liquibase Open Source Change Types for MongoDB, including Change Types that you can without the mongosh native executor, see Liquibase Change Types for MongoDB.

Mongosh integration arguments

Parameter	Type	Description
`--mongosh-args=<string>`	String	Defines extra arguments to pass to the mongosh executable. For more information, see Mongosh documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
`--mongosh-executor=<string>`	String	Name of a custom executor you can specify.
`--mongosh-keep-temp=<true\|false>`	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of Mongosh. If `true`, the file is not deleted. Default: `false`.
`--mongosh-keep-temp-name=<string>`	String	Indicates the name of a temporary SQL file after the execution of Mongosh. If no file name is specified, a name is automatically generated.
`--mongosh-keep-temp-path=<string>`	String	Specify the path in which to store the temporary files after the execution of Mongosh. If not specified, the files will be stored in the system's `temp` directory.
`--mongosh-log-file=<string>`	String	Log file for Mongosh output.
`--mongosh-path=<string>`	String	Path to `mongosh` executable. For example: Linux: `/usr/bin/mongosh` or `/usr/local/bin/mongosh` Windows: `C:\Program Files\MongoDB\Server\6.0\bin\mongosh.exe`
`--mongosh-timeout=<int>`	Integer	Indicates seconds to wait for the `mongosh` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

Parameter	Type	Description
`globalArgs: { mongosh-args: "<string>" }`	String	Defines extra arguments to pass to the mongosh executable. For more information, see Mongosh documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
`globalArgs: { mongosh-executor: "<string>" }`	String	Name of a custom executor you can specify.
`globalArgs: { mongosh-keep-temp: "<true\|false>" }`	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of Mongosh. If `true`, the file is not deleted. Default: `false`.
`globalArgs: { mongosh-keep-temp-name: "<string>" }`	String	Indicates the name of a temporary SQL file after the execution of Mongosh. If no file name is specified, a name is automatically generated.
`globalArgs: { mongosh-keep-temp-path: "<string>" }`	String	Specify the path in which to store the temporary files after the execution of Mongosh. If not specified, the files will be stored in the system's `temp` directory.
`globalArgs: { mongosh-log-file: "<string>" }`	String	Log file for Mongosh output.
`globalArgs: { mongosh-path: "<string>" }`	String	Path to `mongosh` executable. For example: Linux: `/usr/bin/mongosh` or `/usr/local/bin/mongosh` Windows: `C:\Program Files\MongoDB\Server\6.0\bin\mongosh.exe`
`globalArgs: { mongosh-timeout: "<int>" }`	Integer	Indicates seconds to wait for the `mongosh` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

Parameter	Type	Description
`liquibase.mongosh.args: <string>`	String	Defines extra arguments to pass to the mongosh executable. For more information, see Mongosh documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
`liquibase.mongosh.executor: <string>`	String	Name of a custom executor you can specify.
`liquibase.mongosh.keep.temp: <true\|false>`	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of Mongosh. If `true`, the file is not deleted. Default: `false`.
`liquibase.mongosh.keep.temp.name: <string>`	String	Indicates the name of a temporary SQL file after the execution of Mongosh. If no file name is specified, a name is automatically generated.
`liquibase.mongosh.keep.temp.path: <string>`	String	Specify the path in which to store the temporary files after the execution of Mongosh. If not specified, the files will be stored in the system's `temp` directory.
`liquibase.mongosh.logFile: <string>`	String	Log file for Mongosh output.
`liquibase.mongosh.path: <string>`	String	Path to `mongosh` executable. For example: Linux: `/usr/bin/mongosh` or `/usr/local/bin/mongosh` Windows: `C:\Program Files\MongoDB\Server\6.0\bin\mongosh.exe`
`liquibase.mongosh.timeout: <int>`	Integer	Indicates seconds to wait for the `mongosh` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

Parameter	Type	Description
`JAVA_OPTS=-Dliquibase.mongosh.args=<string>`	String	Defines extra arguments to pass to the mongosh executable. For more information, see Mongosh documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
`JAVA_OPTS=-Dliquibase.mongosh.executor=<string>`	String	Name of a custom executor you can specify.
`JAVA_OPTS=-Dliquibase.mongosh.keep.temp=<true\|false>`	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of Mongosh. If `true`, the file is not deleted. Default: `false`.
`JAVA_OPTS=-Dliquibase.mongosh.keep.temp.name=<string>`	String	Indicates the name of a temporary SQL file after the execution of Mongosh. If no file name is specified, a name is automatically generated.
`JAVA_OPTS=-Dliquibase.mongosh.keep.temp.path=<string>`	String	Specify the path in which to store the temporary files after the execution of Mongosh. If not specified, the files will be stored in the system's `temp` directory.
`JAVA_OPTS=-Dliquibase.mongosh.logFile=<string>`	String	Log file for Mongosh output.
`JAVA_OPTS=-Dliquibase.mongosh.path=<string>`	String	Path to `mongosh` executable. For example: Linux: `/usr/bin/mongosh` or `/usr/local/bin/mongosh` Windows: `C:\Program Files\MongoDB\Server\6.0\bin\mongosh.exe`
`JAVA_OPTS=-Dliquibase.mongosh.timeout=<int>`	Integer	Indicates seconds to wait for the `mongosh` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

Parameter	Type	Description
`LIQUIBASE_MONGOSH_ARGS=<string>`	String	Defines extra arguments to pass to the mongosh executable. For more information, see Mongosh documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
`LIQUIBASE_MONGOSH_EXECUTOR=<string>`	String	Name of a custom executor you can specify.
`LIQUIBASE_MONGOSH_KEEP_TEMP=<true\|false>`	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of Mongosh. If `true`, the file is not deleted. Default: `false`.
`LIQUIBASE_MONGOSH_KEEP_TEMP_NAME=<string>`	String	Indicates the name of a temporary SQL file after the execution of Mongosh. If no file name is specified, a name is automatically generated.
`LIQUIBASE_MONGOSH_KEEP_TEMP_PATH=<string>`	String	Specify the path in which to store the temporary files after the execution of Mongosh. If not specified, the files will be stored in the system's `temp` directory.
`LIQUIBASE_MONGOSH_LOG_FILE=<string>`	String	Log file for Mongosh output.
`LIQUIBASE_MONGOSH_PATH=<string>`	String	Path to `mongosh` executable. For example: Linux: `/usr/bin/mongosh` or `/usr/local/bin/mongosh` Windows: `C:\Program Files\MongoDB\Server\6.0\bin\mongosh.exe`
`LIQUIBASE_MONGOSH_TIMEOUT=<int>`	Integer	Indicates seconds to wait for the `mongosh` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

Use Native Executors with MongoDB Pro

Prerequisites

Setup

Using runWith in your changelogs

Native MongoD Shell (mongosh) scripts

runWith and mongosh examples

Formatted Mongo changelogs

XML, YAML, and JSON changelogs

Mongosh integration arguments

Related links

Using `runWith` in your changelogs

Native MongoD Shell (`mongosh`) scripts

`runWith` and `mongosh` examples