migrate-mongo is a database migration tool for MongoDB running in Node.js

Installation

$ npm install -g migrate-mongo

CLI Usage

$ migrate-mongo Usage: migrate-mongo [options] [command] Commands: init initialize a new migration project create [description] create a new database migration with the provided description up [options] run all unapplied database migrations down [options] undo the last applied database migration status [options] print the changelog of the database Options: -h, --help output usage information -V, --version output the version number

Quickstart

Initialize a new project

Make sure you have Node.js 10 (or higher) installed.

Create a directory where you want to store your migrations for your mongo database (eg. 'albums' here) and cd into it

$ mkdir albums-migrations $ cd albums-migrations

Initialize a new migrate-mongo project

$ migrate-mongo init Initialization successful. Please edit the generated migrate-mongo-config.js file

The above command did two things:

create a sample 'migrate-mongo-config.js' file and create a 'migrations' directory

Edit the migrate-mongo-config.js file. An object or promise can be returned. Make sure you change the mongodb url:

module . exports = { mongodb : { url : " mongodb://localhost:27017 " , databaseName : " YOURDATABASENAME " , options : { useNewUrlParser : true } } , migrationsDir : " migrations " , changelogCollectionName : " changelog " , migrationFileExtension : " .js " } ;

Alternatively, you can also encode your database name in the url (and leave out the databaseName property):

url: "mongodb://localhost:27017/YOURDATABASE",

Creating a new migration script

To create a new database migration script, just run the migrate-mongo create [description] command.

For example:

$ migrate-mongo create blacklist_the_beatles Created: migrations/20160608155948-blacklist_the_beatles.js

A new migration file is created in the 'migrations' directory:

module . exports = { up ( db , client ) { } , down ( db , client ) { } } ;

Edit this content so it actually performs changes to your database. Don't forget to write the down part as well. The db object contains the official MongoDB db object The client object is a MongoClient instance (which you can omit if you don't use it).

There are 3 options to implement the up and down functions of your migration:

Return a Promises Use async-await Call a callback (DEPRECATED!)

Always make sure the implementation matches the function signature:

function up(db, client) { /* */ } should return Promise

should return function async up(db, client) { /* */ } should contain await keyword(s) and return Promise

should contain keyword(s) and return function up(db, client, next) { /* */ } should callback next

Example 1: Return a Promise

module . exports = { up ( db ) { return db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : true } } ) ; } , down ( db ) { return db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : false } } ) ; } } ;

Example 2: Use async & await

Async & await is especially useful if you want to perform multiple operations against your MongoDB in one migration.

module . exports = { async up ( db ) { await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : true } } ) ; await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Doors ' } , { $set : { stars : 5 } } ) ; } , async down ( db ) { await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Doors ' } , { $set : { stars : 0 } } ) ; await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : false } } ) ; } , } ;

Example 3: Call a callback (deprecated)

Callbacks are supported for backwards compatibility. New migration scripts should be written using Promises and/or async & await. It's easier to read and write.

module . exports = { up ( db , callback ) { return db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : true } } , callback ) ; } , down ( db , callback ) { return db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : false } } , callback ) ; } } ;

Overriding the sample migration

To override the content of the sample migration that will be created by the create command, create a file sample-migration.js in the migrations directory.

Checking the status of the migrations

At any time, you can check which migrations are applied (or not)

$ migrate-mongo status ┌─────────────────────────────────────────┬────────────┐ │ Filename │ Applied At │ ├─────────────────────────────────────────┼────────────┤ │ 20160608155948-blacklist_the_beatles.js │ PENDING │ └─────────────────────────────────────────┴────────────┘

Migrate up

This command will apply all pending migrations

$ migrate-mongo up MIGRATED UP: 20160608155948-blacklist_the_beatles.js

If an an error occurred, it will stop and won't continue with the rest of the pending migrations

If we check the status again, we can see the last migration was successfully applied:

$ migrate-mongo status ┌─────────────────────────────────────────┬──────────────────────────┐ │ Filename │ Applied At │ ├─────────────────────────────────────────┼──────────────────────────┤ │ 20160608155948-blacklist_the_beatles.js │ 2016-06-08T20:13:30.415Z │ └─────────────────────────────────────────┴──────────────────────────┘

Migrate down

With this command, migrate-mongo will revert (only) the last applied migration

$ migrate-mongo down MIGRATED DOWN: 20160608155948-blacklist_the_beatles.js

If we check the status again, we see that the reverted migration is pending again:

$ migrate-mongo status ┌─────────────────────────────────────────┬────────────┐ │ Filename │ Applied At │ ├─────────────────────────────────────────┼────────────┤ │ 20160608155948-blacklist_the_beatles.js │ PENDING │ └─────────────────────────────────────────┴────────────┘

Extra tips and tricks

Using a custom config file

All actions (except init ) accept an optional -f or --file option to specify a path to a custom config file. By default, migrate-mongo will look for a migrate-mongo-config.js config file in of the current directory.

$ migrate-mongo status -f ' ~/configs/albums-migrations.js ' ┌─────────────────────────────────────────┬────────────┐ │ Filename │ Applied At │ ├─────────────────────────────────────────┼────────────┤ │ 20160608155948-blacklist_the_beatles.js │ PENDING │ └─────────────────────────────────────────┴────────────┘

Using npm packages in your migration scripts

You can use use Node.js modules (or require other modules) in your migration scripts. It's even possible to use npm modules, just provide a package.json file in the root of your migration project:

$ cd albums-migrations $ npm init --yes

Now you have a package.json file, and you can install your favorite npm modules that might help you in your migration scripts. For example, one of the very useful promise-fun npm modules.

Using MongoDB's Transactions API

You can make use of the MongoDB Transaction API in your migration scripts.

Note: this requires both:

MongoDB 4.0 or higher

migrate-mongo 7.0.0 or higher

migrate-mongo will call your migration up and down function with a second argument: client . This client argument is an MongoClient instance, it gives you access to the startSession function.

Example:

module . exports = { async up ( db , client ) { const session = client . startSession ( ) ; try { await session . withTransaction ( async ( ) => { await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : true } } ) ; await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Doors ' } , { $set : { stars : 5 } } ) ; } ) ; } finally { await session . endSession ( ) ; } } , async down ( db , client ) { const session = client . startSession ( ) ; try { await session . withTransaction ( async ( ) => { await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Beatles ' } , { $set : { blacklisted : false } } ) ; await db . collection ( ' albums ' ) . updateOne ( { artist : ' The Doors ' } , { $set : { stars : 0 } } ) ; } ) ; } finally { await session . endSession ( ) ; } } , } ;

Version

To know which version of migrate-mongo you're running, just pass the version option:

$ migrate-mongo version

API Usage

const { init , create , database , config , up , down , status } = require ( ' migrate-mongo ' ) ;

init() → Promise

Initialize a new migrate-mongo project

await init ( ) ;

The above command did two things:

create a sample migrate-mongo-config.js file and create a migrations directory

Edit the migrate-mongo-config.js file. Make sure you change the mongodb url.

For example:

const fileName = await create ( ' blacklist_the_beatles ' ) ; console . log ( ' Created: ' , fileName ) ;

A new migration file is created in the migrations directory.

Connect to a mongo database using the connection settings from the migrate-mongo-config.js file.

const { db , client } = await database . connect ( ) ;

Read connection settings from the migrate-mongo-config.js file.

const mongoConnectionSettings = await config . read ( ) ;

Tell migrate-mongo NOT to use the migrate-mongo-config.js file, but instead use the config object passed as the first argument of this function. When using this feature, please do this at the very beginning of your program.

Example:

const { config , up } = require ( ' ../lib/migrate-mongo ' ) ; const myConfig = { mongodb : { url : " mongodb://localhost:27017/mydatabase " , options : { useNewUrlParser : true } } , migrationsDir : " migrations " , changelogCollectionName : " changelog " , migrationFileExtension : " .js " } ; config . set ( myConfig ) ; await up ( ) ;

Apply all pending migrations

const { db , client } = await database . connect ( ) ; const migrated = await up ( db , client ) ; migrated . forEach ( fileName => console . log ( ' Migrated: ' , fileName ) ) ;

If an an error occurred, the promise will reject and won't continue with the rest of the pending migrations.

Revert (only) the last applied migration

const { db , client } = await database . connect ( ) ; const migratedDown = await down ( db , client ) ; migratedDown . forEach ( fileName => console . log ( ' Migrated Down: ' , fileName ) ) ;

status(MongoDb) → Promise<Array<{ fileName, appliedAt }>>

Check which migrations are applied (or not.

const { db } = await database . connect ( ) ; const migrationStatus = await status ( db ) ; migrationStatus . forEach ( ( { fileName , appliedAt } ) => console . log ( fileName , ' : ' , appliedAt ) ) ;

client.close() → Promise

Close the database connection