A database migration tool for MongoDB in Node.
$ npm install -g migrate-mongo
$ 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
Make sure you have Node.js 8.0.0 (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:
// In this file you can configure migrate-mongo
module.exports = {
mongodb: {
// TODO Change (or review) the url to your MongoDB:
url: "mongodb://localhost:27017",
// TODO Change this to your database name:
databaseName: "YOURDATABASENAME",
options: {
useNewUrlParser: true // removes a deprecation warning when connecting
// connectTimeoutMS: 3600000, // increase connection timeout to 1 hour
// socketTimeoutMS: 3600000, // increase socket timeout to 1 hour
}
},
// The migrations dir, can be an relative or absolute path. Only edit this when really necessary.
migrationsDir: "migrations",
// The mongodb collection where the applied changes are stored. Only edit this when really necessary.
changelogCollectionName: "changelog"
};
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) {
// TODO write your migration here. Return a Promise (and/or use async & await).
// See https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script
// Example:
// return db.collection('albums').updateOne({artist: 'The Beatles'}, {$set: {blacklisted: true}});
},
down(db, client) {
// TODO write the statements to rollback your migration (if possible)
// Example:
// return db.collection('albums').updateOne({artist: 'The Beatles'}, {$set: {blacklisted: false}});
}
};
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 returnPromise
function async up(db, client) { /* */ }
should containawait
keyword(s) and returnPromise
function up(db, client, next) { /* */ }
should callbacknext
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}});
}
};
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}});
},
};
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);
}
};
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.
At any time, you can check which migrations are applied (or not)
$ migrate-mongo status
┌─────────────────────────────────────────┬────────────┐
│ Filename │ Applied At │
├─────────────────────────────────────────┼────────────┤
│ 20160608155948-blacklist_the_beatles.js │ PENDING │
└─────────────────────────────────────────┴────────────┘
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 │
└─────────────────────────────────────────┴──────────────────────────┘
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 │
└─────────────────────────────────────────┴────────────┘
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 │
└─────────────────────────────────────────┴────────────┘
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.
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();
}
},
};
const {
init,
create,
database,
config,
up,
down,
status
} = require('migrate-mongo');
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();
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));
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));
Close the database connection
const { db, client } = await database.connect();
await client.close();