Migrations using ORM2's model DSL leveraging Visionmedia's node-migrate.
Heads up ! v3 introduce some major changes, make sure you check the changelog
Installation
npm install migrate-orm2
Usage
The example below uses MySQL. Locomote uses migrate-orm2 with Postgres. Testing was also done with SQLite3, though some driver issues were encountered.
Build a connection & construct the migrate-orm2 Task object:
const orm = require('orm');const MigrateTask = require('migrate-orm2');orm.connect(connectionString, function (err, connection) { if (err) throw err; const task = new MigrateTask(connection.driver, { extensions: ['js', 'ts'] });});
Options
coffee: enable coffeescript v1 support (default: false)
dir: migrations directory (default: "migrations")
extensions: file extensions of supported migration files (default: ['js'])
logger: defaults to using console
The Task constructor function can support options allowing for a custom migrations directory and/or coffeescript support (see 'Usage - opts' below).
A Task object offers three operations - generate, up and down.
The 'migrations' folder is the default but can be overridden in the opts argument (see 'Usage - opts' below).
A skeleton migration file now exists and can be populated with the ORM2 DSL.
A simple example, taken from the tests:
exports.up = function (next) { this.createTable('test_table', { id : { type : "serial", key: true }, // auto increment name : { type : "text", required: true } }, next);};exports.down = function (next){ this.dropTable('test_table', next);};
You can also write Promise-based migrations, same example, but with no callbacks specified:
exports.up = function () { return this.createTable('test_table', { id : { type : "serial", key: true }, // auto increment name : { type : "text", required: true } });};exports.down = function (){ return this.dropTable('test_table');};
Both createTable and dropTable, along with other MigrationDSL methods return promises if callback is
not specified. Look here for more examples.
There are no built-in operations for inserting, updating, or deleting row data contained in tables. The execQuery operation, which can be used to execute any custom queries, can however be used to perform such actions:
exports.up = function (next) { this.execQuery('INSERT INTO agency (email) VALUES (?)', ['info@example.com'], next);};exports.down = function (next) { this.execQuery('DELETE FROM agency WHERE email = ?', ['info@example.com'], next);};
The full list of operations available through this:
createTable
renameTable
dropTable
addColumn
dropColumn
addIndex
dropIndex
addPrimaryKey
dropPrimaryKey
addForeignKey
addForeignKeyConstraint
dropForeignKey
dropForeignKeyConstraint
execQuery
These operations are depicted in the examples folder.
We would like to add modifyColumn functionality in the future.
Usage - up
> task.up(function(e,r){});> up : migrations/001-create-users.js migration : complete
Alternatively, when there are many migrations, a filename can be specified:
This means 'run up to this migration then execute its up function, then stop.'
Usage - down
> task.down(function(e,r){});> down : migrations/001-create-users.js migration : complete
This means 'rollback the last migration'.
If there are many migrations to rollback a limit can be specified.
> task.down('001-create-users.js', function(e,r){});> down : migrations/001-create-users.js migration : complete
This means 'rollback all migrations including 001-create-users.js'
Usage - the orm_migrations table
Migrate-orm2 maintains an internal orm_migrations table which allows it to run from previous state.
The table contains a list of migrations applied to the database. By comparing these and the migration files, we can decide on which migrations to run.
mysql> select * from orm_migrations;+---------------------+| migration |+---------------------+| 001-create-users.js |+---------------------+1 rows in set (0.00 sec)
Usage - opts
The Task object can be modified to work from a different directory or to generate and cooperate with coffee-script migrations.
var task = new Task(connection, {dir: 'data/migrations', coffee: true});
♪ node-orm-migrate git:(master) ✗ migrate --help Usage: migrate [options] Options: -h, --help output usage information -V, --version output the version number -g, --generate Generate a migration -u, --up Run up migrations -d, --down Run down migrations
Usage - Promises
Task methods (up, down, generate) now support Promises allong with callback.
In case if you don't pass callback to those methods, they will return a Promise.
In this example task.down() will return a Promise:
> task.down();> down : migrations/001-create-users.js migration : complete
Same approach works for task.up and task.generate.
Usage - grunt
We handcraft grunt and our tasks looks this.
Firstly, we have a helper file which knows how to build the connection and opts and invoke the Task object:
var MigrationTask = require('migrate-orm2');var orm = require('orm');exports.runMigration = function (operation, grunt, done) { orm.settings.set("connection.debug", true); orm.connect('mysql://root@localhost/ninja', function (err, connection) { if (err) throw(err); var migrationTask = new MigrationTask( connection.driver, { dir: 'data/migrations'} ); migrationTask[operation](grunt.option('file'), done); });
Registering the Grunt tasks looks like this:
grunt.registerTask('migrate:generate', '', function () { var done = this.async(); require('./tasks/db').runMigration('generate', grunt, done);});grunt.registerTask('migrate:up', '', function () { var done = this.async(); require('./tasks/db').runMigration('up', grunt, done);});grunt.registerTask('migrate:down', '', function () {
To generate a migration file or to indicate a direction: