migrate-mongo-ts

A database migration tool for MongoDB in Node, fork from migrate-mongo (https://www.npmjs.com/package/migrate-mongo)

Installation

$ npm install -g migrate-mongo-ts

CLI Usage

$ migrate-mongo-ts
Usage: migrate-mongo-ts [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.ts 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-ts project

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

The above command did two things:

1. create a sample 'migrate-mongo-config.ts' file and
2. create a 'migrations' directory

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

// In this file you can configure migrate-mongo

export default {
  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"
}

Creating a new migration script

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

For example:

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

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

import { Db } from 'mongodb';

export async function up(db: Db) {
  // TODO write your migration here.
  // See https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script
  // Example:
  // await db.collection('albums').updateOne({artist: 'The Beatles'}, {$set: {blacklisted: true}});
}

export async function down(db: Db) {
  // TODO write the statements to rollback your migration (if possible)
  // Example:
  // await 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:

1. Return a Promises
2. Use async-await

Always make sure the implementation matches the function signature:

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

Checking the status of the migrations

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

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

Migrate up

This command will apply all pending migrations

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

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-ts status
┌─────────────────────────────────────────┬──────────────────────────┐
│ Filename                                │ Applied At               │
├─────────────────────────────────────────┼──────────────────────────┤
│ 20160608155948-blacklist_the_beatles.ts │ 2016-06-08T20:13:30.415Z │
└─────────────────────────────────────────┴──────────────────────────┘

Migrate down

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

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

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

$ migrate-mongo-ts status
┌─────────────────────────────────────────┬────────────┐
│ Filename                                │ Applied At │
├─────────────────────────────────────────┼────────────┤
│ 20160608155948-blacklist_the_beatles.ts │ 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-ts will look for a migrate-mongo-config.ts config file in of the current directory.

Example:

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

Using npm packages in your migration scripts

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

$ cd albums-migrations
$ npm init --yes

Now you have a package.tson 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-ts 7.0.0 or higher

migrate-mongo-ts 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.