What support does Liquibase have for native executors with MongoDB Pro?

Last updated: July 14, 2025

Using runWith in your changelogs

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

You can write Liquibase changelogs in the MongoDB Pro extension in these 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 scripts must be saved as .js files.

  • YAML, JSON, and XML modeled changelogs: Specify changes for Liquibase to deploy without the need for MQL scripts. You can also deploy MQL scripts from YAML, JSON, and XML changelogs using the mongo and mongoFile Change Types. When doing so, you must 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 in formatted Mongo changelogs

With 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.customers.drop()

XML, YAML, and JSON changelogs

db.createCollection('customers');

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 mongoshexecutable. 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. This setting is not required to keep the temporary file, only create-spool is. 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 Mongoshoutput.

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

What support does Liquibase have for native executors with MongoDB Pro? - Liquibase