Using mongosh in Your Changelog
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 JavaScript – Let developers use Liquibase without modifying existing scripts - Formatted Mongo changelogs (MongoDB Pro 1.3.0+) – Add Liquibase changeset metadata to your
mongosh
scripts to use features like rollback, contexts, labels, and theinclude
andincludeAll
tags - XML, YAML, and JSON modeled changelogs – Specify
mongosh
scripts using themongo
andmongoFile
Change Types and create root changelogs to useinclude
andincludeAll
Native MongoDB Shell (mongosh
) scripts
The MongoDB Pro extension lets you use MongoDB's native language of JavaScript in 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');
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 JavaScript directly in Liquibase.
All Liquibase formatted Mongo changelogs must use the file extension .JS
or .js
. 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
You can use XML, YAML, or JSON "modeled" changelogs instead of writing plain or Formatted Mongo scripts in JavaScript. XML, YAML, and JSON changelogs have all the functionality of a Formatted Mongo changelog, like specifying metadata tags and including other changelogs. You must specify mongosh
as the value of runWith
in each changeset.
In a modeled changelog, you can specify mongosh
code within the mongo
and mongoFile
Change Types. Liquibase then implements this in your database. However, the actual mongosh
you specify is the same as in Formatted Mongo.
If you want to use the include
or includeAll
tag in a root changelog, it must be an XML, YAML, or JSON file. The child changelogs you reference can be written in Formatted Mongo, XML, YAML, or JSON.
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 JavaScript directly in Liquibase.
All Liquibase formatted Mongo changelogs must use the file extension .JS
or .js
. 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()
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>
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()"
}
}
]
}
}
]
}
Alternatively, you can specify some Change Type behavior using the MongoDB Liquibase Open Source syntax, which is included in your MongoDB Liquibase Pro installation. These Change Types run corresponding commands in MongoDB. This syntax is only valid for XML, YAML, and JSON changelogs.
For a list of all Pro and OSS MongoDB Change Types and full syntax examples, see Liquibase Change Types for MongoDB.