node package manager


node.js database migration tool for mongodb, sqlite, postgres, mysql


east - node.js database migration tool for different databases (extensible via adapters)

npm install east -g

alternatively you could install it locally

go to project dir and run

east init

after that you can create, migrate, rollback your migrations.

Run east -h to see all commands:

  Usage: east [options] [command]
    init                   initialize migration system
    create <basename>      create new migration based on template
    migrate [options]      run all or selected migrations
    rollback [options]     rollback all or selected migrations
    list [status]          list migration with selected status (`new``executed` or `all`)`new` by default
    -h, --help           output usage information
    -V, --version        output the version number
    --adapter <name>     which db adapter to use
    --config <path>      config file to use
    --timeout <timeout>  timeout for migrate/rollback
    --template <path>    path to template for new migrations
    --dir <dir>          dir where migrations stored
    --url <url>          db connect url
    --trace              verbose mode (including error stack trace)

run east <command> -h to see detail command help.

All options described above can be set via command line or at .eastrc file located at current directory, e.g.:

"dir": "./dbmigration",
"template": "./lib/node/utils/customMigrationTemplate.js"

.eastrc also can be a regular nodejs script (instead of json file):

var path = require('path');
module.exports = {
    dir: path.join(__dirname, 'dbmigration'),
    template: './lib/node/utils/customMigrationTemplate.js'
east create doSomething

produces something like this

New migration `1_doSomething` created at migrations/1_doSomething.js

created file will contain

exports.migrate = function(clientdone) {
exports.rollback = function(clientdone) {

client is connect to current db and he determined by adapter (see adapters section) done is function which should be called at the end of migration (if any error occured you can pass it as first argument) migration also can be synchronous - declare only client at migrate or rollback rollback function is optional and may be omitted

Migration file is normal node.js module and you can migrate any database e.g.

// include your database wrapper which you already use in app 
var db = require('./db');
exports.migrate = function(clientdone) {
    db.connect(function(err) {
        if (err) done(err);
        db.things.insert({_id: 1, name: 'apple', color: 'red'}, done);
exports.rollback = function(clientdone) {
    db.connect(function(err) {
        if (err) done(err);
        db.things.remove({_id: 1}, done);

or you can use special adapter for database (see adapters section)

let's create one more migration

east create doSomethingElse

then executes both of them

east migrate

it sequentially executes all new migrations and produces

target migrations:
migrate `1_doSomething`
migration done
migrate `2_doSomethingElse`
migration done

selected migrations can be executed by passing their names (or numbers or basenames or paths) as argument

east migrate 1_doSomething 2

in our case this command will skip all of them

skip `1_doSomething` because it`s already executed
skip `2_doSomethingElse` because it`s already executed
nothing to migrate

you can pass --force option to execute already executed migrations. This is useful while you develop and test your migration.

You also can export tags array from migration and then migrate only migrations with selected tag specified by --tag option.

rollback has similar to migrate command syntax but executes rollback function from migration file

east rollback

will produce

target migrations:
rollback `2_doSomethingElse`
migration successfully rolled back
rollback `1_doSomething`
migration successfully rolled back
east list

shows new migrations e.g.

new migrations:

target status could be specified as an argument e.g.

east list executed

adapter determines where executed migration names will be stored and what will be passed to migrate and rollback function as client. Default adapter store executed migration names at file .migrations which is located at migrations directory and pass null as client.

Other adapters:

into cloned repository run

npm test

For writing your own adapter you should implement methods for connection, mark transaction as executed, etc see details inside built-in adapter and other adapters.

You also can run tests from current repository against your adapter:

  • Clone current repository
  • Create file .eastrc inside test directory with path and parameters for your adapter e.g.
    "adapter": "../../east-mysql/lib/adapter",
    "url": "mysql://user:password@localhost/east_test_db",
    "createDbOnConnect": true
  • Run npm test at root of the cloned repository.