A simple migration system for mongodb supporting up/downwards migrations.

Status

Installation

Migrations can be installed through yarn or npm. Type:

1$ npm install mgdb-migrator

or

1$ yarn add mgdb-migrator

API

Basics

Import and use the migrator instance - migrator. User the migrator to configure and setup your migration

1import { migrator } from 'mgdb-migrator';
2
3migrator.config({
4  // false disables logging
5  log: true,
6  // null or a function
7  logger: (level, ...args) => console.log(level, ...args),
8  // enable/disable info log "already at latest."
9  logIfLatest: true,
10  // migrations collection name. Defaults to 'migrations'
11  collectionName: 'migrations',
12  // mongdb connection properties object or mongo Db instance
13  db: {
14    // mongdb connection url
15    connectionUrl: 'your connection string',
16    // optional database name, in case using it in connection string is not an option
17    name: 'your database name',
18    // optional mongdb Client options
19    // see https://mongodb.github.io/node-mongodb-native/4.1/interfaces/MongoClientOptions.html
20    // options {
21    //  ...
22    // },
23  },
24}); // Returns a promise

Or ...

Define a new instance of migrator and configure it as you see fit

1import { Migrator } from 'mgdb-migrator';
2
3var migrator = new Migrator({
4  // false disables logging
5  log: true,
6  // null or a function
7  logger: (level, ...args) => console.log(level, ...args),
8  // enable/disable info log "already at latest."
9  logIfLatest: true,
10  // migrations collection name
11  collectionName: 'migrations',
12  // mongdb connection properties object or mongo Db instance
13  db: {
14    // mongdb connection url
15    connectionUrl: 'your connection string',
16    // optional database name, in case using it in connection string is not an option
17    name: 'your database name',
18    // optional mongdb Client options
19    // see https://mongodb.github.io/node-mongodb-native/4.1/interfaces/MongoClientOptions.html
20    // options {
21    //  ...
22    // },
23  },
24});
25await migrator.config(); // Returns a promise

To write a simple migration, somewhere in the server section of your project define:

1migrator.add({
2  version: 1,
3  up: function (db, logger) {
4    // use `db`(mongo driver Db instance) for migration setup to version 1
5    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
6  },
7});

To run this migration to the latest version:

1migrator.migrateTo('latest');

Advanced

A more complete set of migrations might look like:

1migrator.add({
2  version: 1,
3  name: 'Name for this migration',
4  up: function (db, logger) {
5    // use `db`(mongo driver Db instance) for migration setup to version 1.
6    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
7  },
8  down: function (db, logger) {
9    // use `db`(mongo driver Db instance) for migration setup to version 0
10    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
11  },
12});
13
14migrator.add({
15  version: 2,
16  name: 'Name for this migration',
17  up: function (db, logger) {
18    // use `db`(mongo driver Db instance) for migration setup to version 2
19    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
20  },
21  down: function (db, logger) {
22    // use `db`(mongo driver Db instance) for migration setup to version 1
23    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
24  },
25});

Control execution flow with async/await (promises):

1migrator.add({
2  version: 2,
3  name: 'Name for this migration',
4  up: async function(db, logger) {
5    // use `db`(mongo driver Db instance) for migration setup to version 2
6    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
7     await db.collections('someCollection')....
8  },
9  down: async function(db, logger) {
10    // use `db`(mongo driver Db instance) for migration setup to version 1
11    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
12    await db.collections('someCollection')....
13  }
14});

As in 'Basics', you can migrate to the latest by running:

1migrator.migrateTo('latest');

By specifying a version, you can migrate directly to that version (if possible). The migration system will automatically determine which direction to migrate in.

In the above example, you could migrate directly to version 2 by running:

1migrator.migrateTo(2);

If you wanted to undo all of your migrations, you could migrate back down to version 0 by running:

1migrator.migrateTo(0);

Sometimes (usually when somethings gone awry), you may need to re-run a migration. You can do this with the rerun subcommand, like:

1migrator.migrateTo('3,rerun');

To see what version the database is at, call:

1migrator.getVersion();

To see what number of migrations configured, call:

1migrator.getNumberOfMigrations();

IMPORTANT:

• You cannot create your own migration at version 0. This version is reserved by migration for a 'vanilla' system, that is, one without any migrations applied.
• If migrating from vT1 to vTz and migration fails from a vTx to vTy, where vTx & vTy are incremental versions between vT1 to vTz, migration will stop at vTx.
• Prefer an async function (async | promise) for both up()/down() setup. This will ensure migration completes before version bump during execution.

Configuration

You can configure Migrator with the config method. Defaults are:

1migrator.config({
2  // Log job run details to console
3  log: true,
4  // Use a custom logger function (level, ...args) => void
5  logger: null,
6  // Enable/disable logging "Not migrating, already at version {number}"
7  logIfLatest: true,
8  // migrations collection name to use in the database
9  collectionName: "migrations"
10      // mongdb connection properties object or mongo Db instance
11  db: {
12    // mongdb connection url
13    connectionUrl: "your connection string",
14    // optional database name, in case using it in connection string is not an option
15    name: null,
16    // optional mongdb Client options
17    options: null,
18  }
19});

Logging

Migrations uses console by default for logging if not provided. If you want to use your own logger (for sending to other consumers or similar) you can do so by configuring the logger option when calling migrator.config .

Migrations expects a function as logger, and will pass an argument with properties level, message, to it for you to take action on.

1var MyLogger = function(opts) {
2  console.log('Level', opts.level);
3  console.log('Message', opts.message);
4}
5
6Migrator.config({
7  ...
8  logger: MyLogger
9  ...
10});
11

The opts object passed to MyLogger above includes level, message, and any other additional info needed.

• level will be one of info, warn, error, debug.
• message is something like Finished migrating..

Development

Run docker-compose to execute lib in dev mode

1$ npm run docker:dev

Test

Run docker-compose to execute lib in test mode

1$ npm run docker:test

Credits

Migration builds on percolatestudio/meteor-migrations with the goal of creating a generic mongodb migration library