Programable API

This API is intended for the usage with db-migrate as a module and consists out of several functions.

Using db-migrate as module

You can always find example on how to use the API in our example project:

https://github.com/db-migrate/api-examples

To get an instance of db-migrate you need to call it in your application like the following:

var DBMigrate = require('db-migrate');
var assert = require('assert');

//getting an instance of dbmigrate
var dbmigrate = DBMigrate.getInstance(true);

//execute any of the API methods
dbmigrate.reset()
.then( () => dbmigrate.up() );

Handle the onComplete callback outside of db-migrate

If you want to handle the onComplete callback in your own project you can do this like this:

function specialCallback(migrator, originalError) {
  migrator.driver.close(function(err) {
    assert.ifError(originalErr);
    assert.ifError(err);
    log.info('Done');
  });
}

//specify an own callback, to handle errors on your side of the application.
var dbmigrate_2 = DBMigrate.getInstance(true, specialCallback);

Start the CLI mode

If you need to use the CLI mode and just made some customizations you can do this via the following example:

//get an instance and call the standard runtime behavior
var dbmigrate_3 = DBMigrate.getInstance();
dbmigrate_3.run();

getInstance(isModule, options, callback)

Get an instance of the db-migrate API.

Arguments

  • isModule - set true to return the API as a node module
  • options - hash of various options
  • callback - custom callback

Options

  • cwd - working directory (default: process.cwd)
  • config
    • string - location of the database.json file
    • object - hash of configuration options
  • cmdOptions - hash of CMD options from Basic Usage
  • env - the environment to run the migrations under
  • throwUncatched - Throw an error instead of calling process.exit(1)

Programable API

registerAPIHook([callback])

Register all API hooks and initializes them. This needs to be executed before run is being executed.

Arguments

  • callback - custom callback

Examples

var dbm = dbmigrate.getInstance(true);
dbm.registerAPIHook()
.then(function() {

  dbm.run();
});

run()

Executes the default post initialization CLI behavior.

Examples

var dbm = dbmigrate.getInstance(true);
dbm.run();

up([[specification][count], [scope], [callback]])

Migrates in upwards direction. This is equal to the CLI UP.

Arguments

  • specification - Migration to migrate up to needs to start with this string
  • count - Number of migrations to be executed.
  • scope - Scope to be used or omitted.
  • callback - custom callback, omitted if using Promises

Examples

var dbm = dbmigrate.getInstance(true);
dbm.up(12)
.then(function() {

  console.log('successfully migrated 12 migrations up');
  return;
});

down([[specification][count], [scope], [callback]])

Migrates in downwards direction. This is equal to the CLI DOWN.

Arguments

  • specification - Migration to migrate down to needs to start with this string
  • count - Number of migrations to be executed.
  • scope - Scope to be used or omitted.
  • callback - custom callback, omitted if using Promises

Examples

var dbm = dbmigrate.getInstance(true);
dbm.down(12)
.then(function() {

  console.log('successfully migrated 12 migrations down');
  return;
});

sync([[specification][count], [scope] [callback]])

Migrates to the specified migration and automatically detects if it needs to migrate up or down. This is equal to the CLI SYNC.

Arguments

  • specification - Migration which is the destination and which needs to start with this string
  • scope - Scope to be used or omitted.
  • callback - custom callback, omitted if using Promises

Examples

var dbm = dbmigrate.getInstance(true);
dbm.sync('20150207135259')
.then(function() {

  console.log('successfully migrated 12 migrations up');
  return;
});

reset([[scope], [callback]])

Migrates all currently executed migrations down.

Arguments

  • scope - Scope to be used or omitted.
  • callback - custom callback, omitted if using Promises a Hook. Examples
var dbm = dbmigrate.getInstance(true);
dbm.reset()
.then(function() {

  console.log('successfully resetted all migrations!');
  return;
});

silence(isSilent)

Silences or unsilences logs.

Arguments

  • isSilent - Boolean that silences if true is passed.

Examples

var dbm = dbmigrate.getInstance(true);
dbm.silence(true);
dbm.reset();

transition()

Starts the transmission helper for the dbmigrate protocol migration.

Examples

var dbm = dbmigrate.getInstance(true);
dbm.transition();

create(migrationName[, [scope], [callback]])

Creates a new migration from a template.

Arguments

  • migrationName - The name for the new migration.
  • Scope - The scope to be used, can be omitted
  • callback - custom callback, omitted if using Promises

createDatabase(dbname[, callback])

Creates a database with the name specified.

Arguments

  • dbname - The name of the database.
  • callback - custom callback, omitted if using Promises

dropDatabase(dbname[, callback])

Deletes the specified database.

Arguments

  • dbname - The name of the database.
  • callback - custom callback, omitted if using Promises