Writing Plugins - naturalatlas/migrat GitHub Wiki

All plugins should follow the format of:

var pkg = require('./package.json');

module.exports = function(options) {
   return function(migrat) {
       migrat.setPluginName('myplugin');
       migrat.setPluginVersion(pkg.version);

       // register loaders, templates, etc here
   };    
};

Plugin Components

Loaders

Migration loaders take a migration file and turn it into an object with two methods: up and down (and check optionally):

migrat.registerLoader('*.sql', function(file, callback) {
    callback(null, {
        up: function(context, callback) { ... },
        down: function(context, callback) { ... },
        check: function(context, callback) { ... }
    });
});

Templates

migrat.registerTemplate('sql', function(details, callback) {
    var renderedTemplate = '...';
    callback(null, renderedTemplate);
});

The details object will contain the following fields:

user – Current user creating the migration (USER environment variable)
timestamp – Timestamp of the created migration (milliseconds since epoch).
filename – Filename of the migration being created.

A template can then be used when creating migrations via the --type argument:

$ migrat create somemigration --type sql

Hooks

// invoked at the very beginning of a run before any locks are
// acquired or state is read. use this to establish any connections
// needed for state storage, locks, or context
migrat.registerHook('initialize', function(callback) { ... });

// invoked right before all queued migrations are executed
migrat.registerHook('beforeRun', function(runlist, callback) { ... });

// invoked before each migration
migrat.registerHook('beforeEach', function(runlist_item, callback) { ... });

// invoked after each migration (even if it failed)
migrat.registerHook('afterEach', function(err, runlist_item, callback) { ... });

// invoked after migration run is done (even if it failed)
migrat.registerHook('afterRun', function(err, runlist, callback) { ... });

// invoked at the very tail end of a run once locks are released
// and state has been stored. use this to tear down any
// connections established in `initialize`
migrat.registerHook('terminate', function(callback) { ... });

Locks

Locks are used to prevent race conditions / problems when two machines attempt to run migrations at the same time. For this reason, lock implementations should attempt to operate in a global manner (e.g. lock via a central database, redis server, etc). Be careful to not allow race conditions in the lock implementation itself.

migrat.registerLocker({
    lock: function(callback) {
        // invoke callback once lock has been acquired. if a lock
        // cannot be obtained, pass an error to the callback
    },
    unlock: function(callback) {
        // release the lock, then invoke callback
    }
});

Supporting Classes

MigratRunList

Contains an items property that is an array of runlist items. Each item contains:

method – "up", "down", or "skip"
migration - A MigratMigration instance.

MigratMigration

Contains properties: file, name, type, filename, timestamp.