MongoChains is a database migration tool for MongoDB that uses plain MongoDB javascript to transition a database from one version to another.
There is a .NET Standard Library (MongoChains), and a Console Runner (MongoChains.Console). The former is useful if you want to call MongoChains programatically but most users will probably just want to grab the console runner. MongoChains.Console is a .NET Core application so you can compile it to a native executable for your architecture if necessary.
It can also be integrated easily with build tools such as FAKE, Octopus Deploy, Teamcity etc.
USAGE: mongochains.console [--help] --target <connectionString> --path <path> [--targetversion <version>] [--token <key>=<value>] [--safemode]
OPTIONS:
--target <connectionString>
connection string for the mongo database
--path <path> path to migrations files
--targetversion <version>
target a specific version
--token <key>=<value> a token to be replaced in the migrations
--safemode abort without running scripts if current version of db cannot be determined
--help display this list of options.
Migrations files are just javascript mongo scripts. You should put the migrations into a sequence of numbered directories. Each migration should be called up.js
. For example:
migrations
├───1
│ up.js
│
├───2
│ up.js
│
└───3
up.js
The quickest way to get started is to grab the MongoChains.Console
nuget package and then run it as follows:
dotnet --target "mongodb://localhost:27017" --path "/path/to/migrations"
Migrations may also contain tokens which get replaced before they are applied. This is useful when you have, for example, settings that vary between your development and production environments.
Anything in the javascript files of the form {#Key}
is treated as a case-sensitive token. Before attempting to apply a migration, mongochains will ensure that you have specified values for all the tokens in that file. e.g.
dotnet --target "mongodb://localhost:27017" --path "/path/to/migrations" --token foo=bar --token buzz=bazz
By default, MongoChains will check the current version of the database by looking at the migrations collection in the admin
DB, and will apply in sequence all migrations it finds that are above the current version. You can use the targetversion
parameter to specify a particular version to migrate to. MongoChains migrations only go upwards, so this essentially just ignores migrations above the version you specify.
Finally, there is a safemode
argument that you can specify which causes mongochains to abort early if it cannot determine the current version of the database (that is, there is no record in the migrations collection). This is just an extra sanity check to provide reassurance in production environments.