migrate-mongo

What is migrate-mongo?

The migrate-mongo npm package is a tool for managing MongoDB database migrations. It allows developers to create, run, and manage database schema changes in a controlled and versioned manner.

What are migrate-mongo's main functionalities?

Create a new migration

This feature allows you to create a new migration file. The migration file will be created in the configured migrations directory with a timestamp in its filename.

const migrateMongo = require('migrate-mongo');
migrateMongo.create('my-new-migration').then(() => {
  console.log('Migration created');
});

Run migrations

This feature runs all pending migrations. It ensures that your database schema is up-to-date with the latest changes.

const migrateMongo = require('migrate-mongo');
migrateMongo.up().then((migrated) => {
  console.log('Migrations up:', migrated);
});

Rollback migrations

This feature rolls back the last applied migration. It is useful for undoing changes in case of errors or issues.

const migrateMongo = require('migrate-mongo');
migrateMongo.down().then((migrated) => {
  console.log('Migrations down:', migrated);
});

Configure migrate-mongo

This feature allows you to configure the connection to your MongoDB database and other settings like the migrations directory and changelog collection name.

const migrateMongo = require('migrate-mongo');
const config = {
  mongodb: {
    url: 'mongodb://localhost:27017/mydatabase',
    databaseName: 'mydatabase',
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true
    }
  },
  migrationsDir: 'migrations',
  changelogCollectionName: 'changelog'
};
migrateMongo.config.set(config);

Other packages similar to migrate-mongo

mongodb-migrations

The mongodb-migrations package provides similar functionality for managing MongoDB migrations. It allows you to define and run migrations, but it is less feature-rich and has a simpler API compared to migrate-mongo.

migrate

The migrate package is a general-purpose migration tool that can be used with various databases, including MongoDB. It offers a flexible API and supports custom migration templates, but it requires more setup and configuration compared to migrate-mongo.

umzug

Umzug is a migration framework for Node.js that supports various storage backends, including MongoDB. It is highly customizable and integrates well with Sequelize, but it may require additional setup for MongoDB-specific use cases compared to migrate-mongo.

README

migrate-mongo

A database migration tool for MongoDB in Node.

Installation

$ npm install -g migrate-mongo

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                    run all unapplied database migrations
    down                  undo the last applied database migration
    status                print the changelog of the database

  Options:

    -h, --help  output usage information

Quickstart

Initialize a new project

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 config.js file

The above command did two things: 1) create a sample config.js file and 2) create a 'migrations' directory

Edit the config.js dir, it contains some default values you can edit:

'use strict';

// This is where you can configure migrate-mongo
module.exports = {

  // The mongodb collection where the applied changes are stored:
  changelogCollectionName: 'changelog',

  mongodb: {
    // TODO edit this connection url to your MongoDB database:
    url: 'mongodb://localhost:27017/YOURDATABASENAME'
  }
};

Creating a migration

To create a new migration, 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:

'use strict';

module.exports = {

  up(db, next) {
    // TODO write your migration here
    next();
  },

  down(db, next) {
    // TODO write the statements to rollback your migration (if possible)
    next();
  }

};

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

An example:

'use strict';

module.exports = {

  up(db, next) {
    db.collection('albums').update({artist: 'The Beatles'}, {$set: {blacklisted: true}}, next);
  },

  down(db, next) {
    db.collection('albums').update({artist: 'The Beatles'}, {$set: {blacklisted: false}}, next);
  }
};

The up/down implementation can use either callback-style or return a Promise.

'use strict';

module.exports = {

  up(db) {
    return db.collection('albums').update({artist: 'The Beatles'}, {$set: {blacklisted: true}});
  },

  down(db) {
    return db.collection('albums').update({artist: 'The Beatles'}, {$set: {blacklisted: false}});
  }
};

Make sure the implementation matches the function signature.

• function up(db) { /* */ } should return Promise
• function up(db, next) { /* */ } should callback next

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    │
└─────────────────────────────────────────┴────────────┘

This action accepts an (optional) -f or --file option to provide a custom config file path:

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

Default, it will look for a config.js config file in of the current directory.

Migrate your database 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 │
└─────────────────────────────────────────┴──────────────────────────┘

This action accepts an (optional) -f or --file option to provide a custom config file path. Default, it will look for a config.js config file in of the current directory.

Migrate down

With this command we 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    │
└─────────────────────────────────────────┴────────────┘

This action accepts an (optional) -f or --file option to provide a custom config file path. Default, it will look for a config.js config file in of the current directory.