patelutsav:meteor-migrations

A simple migration system for Meteor supporting string version migrations and command line usage.

Installation

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

    $ meteor add patelutsav:meteor-migrations

API

Basics

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

1    import {Migrations} from 'meteor/patelutsav:meteor-migrations';
2    Migrations.add({
3        version: '1.0.0_1',
4        name: 'Migration Script 1.0.0_1',
5        run: function() {//code to migrate to version 1.0.0_1}
6    });

To run this migration from within your app call:

1    Meteor.startup(() => {
2        Migrations.migrateTo('latest');
3    });

Advanced

A more complete set of migrations might look like:

1    Migrations.add({
2        version: '1.0.0_1',
3        name: 'Migration Script 1.0.0_1',
4        run: function() {
5            //code to migrate to version 1.0.0_1
6        }
7    });
8    Migrations.add({
9        version: '1.0.0_2',
10        name: 'Migration Script 1.0.0_2',
11        run: function() {
12            //code to migrate to version 1.0.0_2
13        }
14    });

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

1    Meteor.startup(function() {
2        Migrations.migrateTo('latest');
3    });

Note: Migrations should be run from Meteor.startup to allow for log output configuration.

By specifying a version, you can run individual migrating script. The migrations system will simply execute the script.

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

1    Migrations.migrateTo('1.0.0_2');

Note: If you are in migration locked state, it will execute the script but it will not change the locked state. For that, you will be able to unlock migration with simple command.

1    Migrations.migrateTo('1.0.0_2');
2    Migrations.unlock();

To see what version are executed, call:

1    Migrations.getExecutedVersions();

Configuration

You can configure Migrations with the config method. Defaults are:

1    Migrations.config({
2        // false disables logging
3        log: true,
4        // null or a function
5        logger: null,
6        // enable/disable info log "already at latest."
7        logIfLatest: true,
8        // stop if old version script added
9        stopIfOldVersionScriptAdded: true,
10        // stop if old version script updated
11        stopIfOldVersionScriptUpdated: true,
12        // migrations collection name
13        statusCollectionName: 'MigrationStatus',
14        listCollectionName: 'MigrationList',
15    });

Logging

Migrations uses Meteor's logging package by default. If you want to use your own logger (for sending to other consumers or similar) you can do so by configuring the logger option.

Migrations expects a function as logger, and will pass arguments to it for you to take action on.

1    var MyLogger = function(opts) {
2        console.log('Level', opts.level);
3        console.log('Message', opts.message);
4        console.log('Tag', opts.tag);
5    }
6
7    Migrations.config({
8        logger: MyLogger
9    });
10
11    Migrations.add({ name: 'Test Job', ... });

The opts object passed to MyLogger above includes level, message, and tag.

• level will be one of info, warn, error, debug.
• message is something like Finished migrating..
• tag will always be "Migrations" (handy for filtering).

Custom collection name

By default, the collection names are MigrationStatus and MigrationList.

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/meteor-migrations/migrate.sh latest

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

$ ./packages/meteor-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 of your clustered app from running migrations simultaneously. If your migrations throw an exception, you will need to manually remove the lock (and ensure your db is still consistent) before re-running the migration.

From the mongo shell update the migrations collection like this:

    $ meteor mongo

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

Alternatively you can unlock the collection from either server code or the meteor shell using:

    Migrations.unlock();

Migrating from other migration package

If you are migrating from other migration package and wish to skip few of the script from running use following:

1    // Adds '2.2.0_1' and '2.2.0_2' to database without running.
2    ['2.2.0_1', '2.2.0_2'].forEach(version => {
3        Migrations.saveMigrationWithoutRunning(version);
4    });
5    // Runs migration scripts after '2.2.0_2'.
6    Migrations.migrateTo('latest');

Contributing

1. Write some code.
2. Write some tests.
3. From this package's local directory, start the test runner:

    $ meteor test-packages ./

4. Open http://localhost:3000/ in your browser to see the test results.

Special Thanks

To: Zoltan Olah

Forked from https://github.com/percolatestudio/meteor-migrations/

License

MIT License