percolate:migrations

v0.7.3Published 9 years ago

This package has not had recent updates. Please investigate it's current state before committing to using it in your project.

percolate:migrations (Meteor package)

A simple migration system for Meteor supporting up/downwards migrations and command line usage.

Installation

Meteor Migrations can be installed through Meteor's package manager. Type:

$ meteor add percolatestudio:percolatestudio-migrations

API

Basics

To write a simple migration, somewhere in the server section of your project define:

1Migrations.add({
2  version: 1,
3  up: function() {//code to migrate up to version 1}
4});

To run this migration from within your app call:

1Migrations.migrateTo('latest');

Advanced

A more complete set of migrations might look like:

1Migrations.add({
2  version: 1,
3  name: 'Adds pants to some people in the db.',
4  up: function() {//code to migrate up to version 1}
5  down: function() {//code to migrate down to version 0}
6});
7
8Migrations.add({
9  version: 2,
10  name: 'Adds a hat to all people in the db who are wearing pants.',
11  up: function() {//code to migrate up to version 2}
12  down: function() {//code to migrate down to version 1}
13});

As in 'Basics', you can migrate to the latest by running:

1Migrations.migrateTo('latest');

By specifying a version, you can migrate directly to that version (if possible). The migrations system will automatically determine which direction to migrate in.

In the above example, you could migrate directly to version 2 by running:

1Migrations.migrateTo(2);

If you wanted to undo all of your migrations, you could migrate back down to version 0 by running:

1Migrations.migrateTo(0);

Sometimes (usually when somethings gone awry), you may need to re-run a migration. You can do this with the rerun subcommand, like:

1Migrations.migrateTo('3,rerun');

NOTE: You cannot create your own migration at version 0. This version is reserved by migrations for a 'vanilla' system, that is, one without any migrations applied.

Command line use

*** DEPRECATED ***

This info is for pre 0.9 users as post 0.9 the migrate.sh script is no longer included in the package folder.

You can also run migrations from the command line using the included shell script. This will

  1. Launch your Meteor app
  2. Call Migrations.migrateTo(version)
  3. Exit your app

For instance, from your project's root, run:

$ ./packages/percolatestudio-migrations/migrate.sh latest

You can also specify additional arguments to be passed into meteor, like:

$ ./packages/percolatestudio-migrations/migrate.sh latest --settings ./setting.json

Errors

  1. Not migrating, control is locked

Migrations set a lock when they are migrating, to prevent multiple instances to prevent multiple instances of your clustered app from running migrations simultaneously. If you migrations throw an exception, you will need to manually remove the lock (and ensure your db is still consistent) before re-running the migration. Update the migrations collection like this:

meteor mongo
db.migrations.update({_id:"control"}, {$set:{"locked":false}});
exit

Contributing

Write some code. Write some tests. To run the tests, do:

$ meteor test-packages percolatestudio:percolatestudio-migrations

License

MIT. (c) Percolate Studio

Meteor Migrations was developed as part of the Verso project.