mgdb-migrator

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

Status

Branch	Status
Next
Master

Installation

Migrations can be installed through yarn or npm. Type:

$ npm install mgdb-migrator

or

$ yarn add mgdb-migrator

API

Basics

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

import { migrator } from 'mgdb-migrator';

migrator.config({
  // false disables logging
  log: true,
  // null or a function
  logger: (level, ...args) => console.log(level, ...args),
  // enable/disable info log "already at latest."
  logIfLatest: true,
  // migrations collection name. Defaults to 'migrations'
  collectionName: 'migrations',
  // mongdb connection properties object or mongo Db instance
  db: {
    // mongdb connection url
    connectionUrl: 'your connection string',
    // optional database name, in case using it in connection string is not an option
    name: 'your database name',
    // optional mongdb Client options
    // see https://mongodb.github.io/node-mongodb-native/4.1/interfaces/MongoClientOptions.html
    // options {
    //  ...
    // },
  },
}); // Returns a promise

Or ...

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

import { Migrator } from 'mgdb-migrator';

var migrator = new Migrator({
  // false disables logging
  log: true,
  // null or a function
  logger: (level, ...args) => console.log(level, ...args),
  // enable/disable info log "already at latest."
  logIfLatest: true,
  // migrations collection name
  collectionName: 'migrations',
  // mongdb connection properties object or mongo Db instance
  db: {
    // mongdb connection url
    connectionUrl: 'your connection string',
    // optional database name, in case using it in connection string is not an option
    name: 'your database name',
    // optional mongdb Client options
    // see https://mongodb.github.io/node-mongodb-native/4.1/interfaces/MongoClientOptions.html
    // options {
    //  ...
    // },
  },
});
await migrator.config(); // Returns a promise

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

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

To run this migration to the latest version:

migrator.migrateTo('latest');

Advanced

A more complete set of migrations might look like:

migrator.add({
  version: 1,
  name: 'Name for this migration',
  up: function (db, logger) {
    // use `db`(mongo driver Db instance) for migration setup to version 1.
    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
  },
  down: function (db, logger) {
    // use `db`(mongo driver Db instance) for migration setup to version 0
    // See https://mongodb.github.io/node-mongodb-native/4.1/classes/Db.html for db api
  },
});

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

Control execution flow with async/await (promises):

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

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

migrator.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:

migrator.migrateTo(2);

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

migrator.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:

migrator.migrateTo('3,rerun');

To see what version the database is at, call:

migrator.getVersion();

To see what number of migrations configured, call:

migrator.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:

migrator.config({
  // Log job run details to console
  log: true,
  // Use a custom logger function (level, ...args) => void
  logger: null,
  // Enable/disable logging "Not migrating, already at version {number}"
  logIfLatest: true,
  // migrations collection name to use in the database
  collectionName: "migrations"
      // mongdb connection properties object or mongo Db instance
  db: {
    // mongdb connection url
    connectionUrl: "your connection string",
    // optional database name, in case using it in connection string is not an option
    name: null,
    // optional mongdb Client options
    options: null,
  }
});

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.

var MyLogger = function(opts) {
  console.log('Level', opts.level);
  console.log('Message', opts.message);
}

Migrator.config({
  ...
  logger: MyLogger
  ...
});

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

$ npm run docker:dev

Test

Run docker-compose to execute lib in test mode

$ npm run docker:test

Credits

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