Exciting news!Announcing our $4.6M Series Seed. Learn more
Log in


Package Overview
File Explorer

Advanced tools


A mongoose based migration framework for node with Typescript support


Version published
Yearly downloads
decreased by-39.58%

Weekly downloads




A node based migration framework for mongoose Fork of migrate-mongoose with merged changes from migrate-mongoose


migrate-mongoose is a migration framework for projects which are already using mongoose.

Most other migration frameworks:

  • Use a local state file to keep track of which migrations have been run: This is a problem for PaS providers like heroku where the file system is wiped each time you deploy
  • Not configurable enough: There are not a granular enough controls to manage which migrations get run
  • Rely on a document-level migration: You have to change your application code to run a migration if it hasn't been run on a document you're working with


  • Stores migration state in MongoDB
  • Provides plenty of features such as
    • Access to mongoose models in migrations
    • Use of promises or standard callbacks
    • custom config files or env variables for migration options
    • ability to delete unused migrations
  • Relies on a simple GLOBAL state of whether or not each migration has been called

Getting Started

You can install it locally in your project

npm install migrate-mongoose

and then run

./node_modules/.bin/migrate [command] [options]


Install it globally

npm install -g migrate-mongoose

and then run

migrate [command] [options]


Usage: migrate -d <mongo-uri> [[create|up|down<migration-name>]|list|prune] [optional options] Commands: list Lists all migrations and their current state. create <migration-name> Creates a new migration file. up [migration-name] Migrates all the migration files that have not yet been run in chronological order. Not including [migration-name] will run UP on all migrations that are in a DOWN state. down <migration-name> Rolls back all migrations down to given name (if down function was provided) prune Allows you to delete extraneous migrations by removing extraneous local migration files/database migrations. Options: -d, --dbConnectionUri The URI of the database connection [string] [required] --collection The mongo collection name to use for migrations [string] [default: "migrations"] --es6 use es6 migration templates? [boolean] --md, --migrations-dir The path to the migration files [string] [default: "./migrations"] -t, --template-file The template file to use when creating a migration [string] -c, --change-dir Change current working directory before running anything [string] --autosync Automatically add any migrations on filesystem but not in db to db [boolean] rather than asking interactively (use in scripts) -h, --help Show help [boolean] Examples: node_modules/.bin/migrate list -d mongodb://localhost/migrations node_modules/.bin/migrate create add_users -d mongodb://localhost/migrations node_modules/.bin/migrate up add_user -d mongodb://localhost/migrations node_modules/.bin/migrate down delete_names -d mongodb://localhost/migrations node_modules/.bin/migrate prune -d mongodb://localhost/migrations node_modules/.bin/migrate list --config settings.json

Setting Options Automatically

If you want to not provide the options such as --dbConnectionUri to the program every time you have 2 options.

1. Set the option as an Environment Variable with the prefix MIGRATE_
Using a Javascript file:

//index.js export MIGRATE_dbConnectionUri=localhost/migrations

.env files are also supported:

#.env MIGRATE_dbConnectionUri=localhost/migrations

2. Provide a config file (defaults to migrate.json or migrate.js)

# If you have migrate.json in the directory, you don't need to do anything migrate list # Otherwise you can provide a config file migrate list --config somePath/myCustomConfigFile[.json]

Options Override Order:

Command line args beat Env vars beats Config File

Just make sure you don't have aliases of the same option with 2 different values between env vars and config file

Migration Files

Here's how you can access your mongoose models and handle errors in your migrations

ES5 Example

'use strict'; var lib = require('myLibrary'); /** * Make any changes you need to make to the database here */ exports.up = function up (done) { return lib.doSomeWork().then(function() { // Don't forget to call done() or the migration will never finish! done(); }) .catch(function(error){ // If you get an error in your async operations you can call done like so done(error); }); // Throwing errors also works throw new Error('It should never get here!'); }; /** * Make any changes that UNDO the up function side effects here (if possible) */ exports.down = function down(done) { lib.undoAboveWork().then(function() { done(); }) .catch(function(error){ done(error); }); };

ES6 Example

/** * Easy flow control */ // Notice no need for callback export async function up() { // Error handling is as easy as throwing an error if (condition) { throw new Error('This is an error. Could not complete migration'); } // You can just run your updates and when function finishes the migration is assumed to be done! await new Promise((resolve, reject) => { setTimeout(()=> { resolve('ok'); }, 3000); }); // ======== OR =========== // just return the promise! It will succeed when it resolves or fail when rejected return lib.getPromise(); }

Access to mongoose models

// Lets say you have a user model like this // models/User.js const UserSchema = new Schema({ firstName: String, lastName: String, }); module.exports = mongoose.model('user', UserSchema); // 1459287720919-my-migration.js export async function up() { // Then you can access it in the migration like so await this('user').update({}, { $rename: { firstName: 'first' } }, { multi: true }); // Or something such as const users = this('user').find(); /* Do something with users */ }


Currently, the -d/dbConnectionUri must include the database to use for migrations in the uri. example: -d mongodb://localhost:27017/development . If you don't want to pass it in every time feel free to use the migrate.json config file or an environment variable

How to contribute

  1. Start an issue. We will discuss the best approach
  2. Make a pull request. I'll review it and comment until we are both confident about it
  3. Profit




Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc