boco-migrate

Migrate all your things (not just databases)!

Table of Contents

• Installation
• Usage
  • Migrating
  • Rolling Back
  • Resetting
  • Storage Adapters
    • File Storage Adapter
    • Redis Storage Adapter
    • Write an Adapter
  • Exceptions
    • Irreversible Migrations
    • Migration not Found
  • Using the CLI

Installation

Installation is available via npm or github.

$ npm install boco-migrate
$ git clone https://github.com/bocodigitalmedia/boco-migrate

Usage

BocoMigrate = require "boco-migrate"
lastMigration = null

# Create a migrator
migrator = new BocoMigrate.Migrator
  storageAdapter: new BocoMigrate.StorageAdapter

# Add migrations, in order
migrator.addMigration
  id: "migration1"
  up: (done) -> lastMigration = @id; done()
  down: (done) -> lastMigration = null; done()

migrator.addMigration
  id: "migration2"
  up: (done) -> lastMigration = @id; done()
  down: (done) -> lastMigration = "migration1"; done()

migrator.addMigration
  id: "migration3"
  up: (done) -> lastMigration = @id; done()
  down: (done) -> lastMigration = "migration2"; done()

Migrating

passing null or undefined runs all pending migrations.

migrator.migrate null, (error) ->
  throw error if error?
  expect(lastMigration).toEqual "migration3"
  ok()

passing a target migrationId migrates to the state of that migration.

migrator.migrate "migration1", (error) ->
  throw error if error?
  expect(lastMigration).toEqual "migration1"
  ok()

Rolling Back

rollback rolls back the latest migration.

migrator.migrate null, (error) ->
  throw error if error?

  migrator.rollback (error) ->
    throw error if error?
    expect(lastMigration).toEqual "migration2"
    ok()

Resetting

reset rolls back all migrations.

migrator.migrate null, (error) ->
  throw error if error?

  migrator.reset (error) ->
    throw error if error?
    expect(lastMigration).toEqual null
    ok()

Storage Adapters

In order for the migrator to persist its state, you must provide it with an adapter for the storage mechanism of your choice.

The default StorageAdapter is non-persistent, and thus is primarily used only for testing or as the parent class for other adapters.

testAdapter = null

testAdapter = (adapter, done) ->
  migrator.setStorageAdapter adapter

  resetAdapter = (done) -> adapter.reset done
  testMigrate = (done) -> migrator.migrate null, done
  testReset = (done) -> migrator.reset done

  series = [resetAdapter, testMigrate, testReset]
  require("async").series series, done

File Storage Adapter

The BocoMigrate.FileStorageAdapter writes data to the JSON file specified by the path provided.

adapter = new BocoMigrate.FileStorageAdapter
  path: "migratorStorage.json"

testAdapter adapter, (error) ->
  expect(error?).toEqual false
  ok()

Redis Storage Adapter

The BocoMigrate.RedisStorageAdapter writes data to a redis instance.

redisClient = require("redis").createClient()

adapter = new BocoMigrate.RedisStorageAdapter
  redisClient: redisClient
  keyPrefix: "migrator"
  keyJoinString: "_"

testAdapter adapter, (error) ->
  expect(error?).toEqual false
  ok()

Writing an Adapter

If you do not see an adapter you need, just subclass the StorageAdapter class and modify it to suit the needs of your storage mechanism. If you end up writing an adapter, please create an issue for your adapter on this repository's github page.

Exceptions

Irreversible Migrations

A migration that has not defined a down method will raise an IrreversibleMigration error.

migrator.addMigration
  id: "migration4"
  up: (done) -> lastMigration = @id; done()

A migration that has not defined a down method will raise an IrreversibleMigration error.

migrator.migrate null, (error) ->
  throw error if error?
  migrator.rollback (error) ->
    expect(error.constructor).toEqual BocoMigrate.IrreversibleMigration
    ok()

Migration not Found

If you pass an id to migrate that is not found, it will raise a MigrationNotFound error.

migrator.migrate "i dont exist", (error) ->
  expect(error.constructor).toEqual BocoMigrate.MigrationNotFound
  ok()

Using the CLI

A CLI is provided with this package to allow you to run your migrations from the command line.

Usage: boco-migrate <options...> <command> [args...]

options:
  -h, --help                   show this help screen
  -e, --example                show an example migrator factory
  -f, --factory=factory_path   path to the migrator factory
                               defaults to "migratorFactory.js"

 commands:
   migrate [migration_id]
     Migrate to the (optional) target migration id
   rollback
     Roll back the latest migration
   reset
     Roll back all migrations
   info
     Show migration information
   set-latest-migration <migration_id>
     Set the latest migration id manually (does not run migrations).
   reset-latest-migration
     Reset the latest migration id.

factory:
  A javascript file that exports a single async factory method,
  returning a migrator instance for the CLI.

Creating a Migrator Factory

Your migrator factory file must export a single async function, and returns a Migrator instance. This allows you to connect to databases and perform other asynchronous tasks to initialize both the migrator as well as your migrations.

// file: "migratorFactory.js"
var MyDBLib = require("my-db-lib");
var MyDBAdapter = require("my-db-adapter");
var MyDBMigrations = require("my-db-migrations");
var Migrator = require("boco-migrate").Migrator;

module.exports = function(done) {

  MyDBLib.connect(function(error, db) {
    var adapter = new MyDBAdapter({ db: db });
    var migrator = new Migrator({ adapter: adapter });
    var migrations = MyDBMigrations.configure({ db: db });

    migrations.forEach(function(migration) {
      migrator.addMigration(migration);
    });

    return done(null, migrator);
};

Copyright (c) 2015 Christian Bradley + Boco Digital Media, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.