README.md

Yammy

Yet another MongoDB migration tool. Unlike other utils it designed to be used in program as a module.

• Yammy
  • Features
  • Installation
    • Requirements
  • Getting started
    • Migration file
    • Configuration
      • Config file
      • Constructor options
    • Usage
      • CLI
      • API
  • API docs
  • License

Features

• Support multiple databases.
• Has backward compatibility with migrate-mongo. You'll just need to specify database name in your migrations.
• Simple API interface.
• Supports and uses transactions by default.

Installation

npm i yammy

Requirements

• Node.js >=8.0.0
• MongoDB
  • >=2.6 - for regular migrations
  • >=4.0 - for transaction support on replica set
  • >=4.2 - for transaction support on shards

Getting started

Migration file

Your migration file should implement Migration interface

/**
 * Target database name
 */
exports.db = 'mydb';

/**
 * Apply migration
 * @param {import('mongodb').Db} db
 * @param {import('mongodb').ClientSession} session
 */
exports.up = async (db, session) => {
  await db.collection('foo').createIndexes(
    [
      {
        key: { bar: 1 },
        name: `bar_1`,
      },
    ],
    { session }
  );
};
/**
 * Rollback migration
 * @param {import('mongodb').Db} db
 * @param {import('mongodb').ClientSession} session
 */
exports.down = async (db, session) => {
  await db.collection('foo').dropIndex(`bar_1`, { session });
};

See other examples.

Configuration

Config file

File format:

module.exports = {
  uri: 'mongodb://localhost',
  changelog: '__changelog__',
  dir: 'migrations',
  options: {
    useNewUrlParser: true,
    useUnifiedTopology: true,
  },
};

By default you Yammy supports following file names: .yammyrc, .yammyrc.json, .yammyrc.js, .migrationsrc, .migrationsrc.json, .migrationsrc.js. Also you can specify your own via --config=path_to_file.

Configuration file is used in only CLI mode. If you want to use it in your app you can require it and pass options to constructor like it shown in (Constructor options)[#constructor-options].

Constructor options

const migrate = new Migrate(
  { uri: 'mongo://localhost', options: {useNewUrlParser: true} },
  { autoClose: true, dir: './migrations' }
);

For more details see constructor

Usage

CLI

As other migration tools it provides common CLI interface that's similar to them.

USAGE
  $ yammy [COMMAND]

COMMANDS
  autocomplete  display autocomplete installation instructions
  create        get migration status
  down          rolls back migrations
  help          display help for yammy
  status        get migration status
  up            applies migrations

Use yammy -h or yammy <command> -h to see available options.

API

You can use this module inside your program or application. It was designed to be used in this way.

import Migrate from 'yammy';
import config from './.yammyrc.json';

const migrate = new Migrate(
  { uri: config.uri, options: config.options },
  { autoClose: true, changelog: config.changelog, dir: config.dir }
);

await migrate.init();
await migrate.down();

See constructor for details.

API docs

See docs

License

MIT