DOCSEARCHbyAlgolia
Submit Docs

percolate:migrations

repository·master·Indexed 42 days ago

https://github.com/meteor/meteor-migrations

A migration system for Meteor that supports up/down migrations and command-line usage to manage database schema changes. It allows developers to define migrations using Migrations.add(), execute them via Migrations.migrateTo(), and manage versioning and rollbacks within MongoDB.

Tokens
1.5K
Snippets
7
Records
7
Agent score
4%

What's inside percolate:migrations

  1. Define and run basic migrations

    master

    To create a migration, use Migrations.add() within your server-side code. To execute migrations, call Migrations.migrateTo() inside Meteor.startup().

    Note: It is recommended to run migrations within Meteor.startup to ensure log output is configured correctly.

    // Define a migration
Migrations.add({
  version: 1,
  up: function() {//code to migrate up to version 1}
});

// Run the migration
Meteor.startup(() => {
  Migrations.migrateTo('latest');
});

  3. Handle asynchronous code in migrations

    master

    Migrations support asynchronous operations.

    For Meteor < 2.8

    Use Meteor.wrapAsync to wrap your async functions and call the next callback to signal completion.

    For Meteor 2.8+

    You can use async functions directly. The migration system will await the completion of the function.

    Tip: If running on platforms like Heroku that limit startup time, you may want to wrap the migration call in a setTimeout to allow the server to finish starting up first.

    // Meteor 2.8+ pattern
Migrations.add({
  version: 3,
  name: 'Add belts to people wearing pants.',
  up: async function () {
    await SomeCollection.updateAsync({ wearsPants: true }, { $set: { hasBelt: true } }, { multi: true });
  },
  down: async function () {
    await SomeCollection.updateAsync({}, { $unset: { hasBelt: true } }, { multi: true });
  },
});

// Startup tip for Heroku
Meteor.startup(function() {
  setTimeout("Migrations.migrateTo('latest')", 0);
});

  4. Configure Migrations settings

    master

    Use Migrations.config() to customize the behavior of the migration system.

    Default configuration options:

    • log: (boolean) Log job run details to console. Defaults to true.
    • logger: (function|null) Custom logger function. Defaults to null (uses Meteor's logging package).
    • logIfLatest: (boolean) Enable/disable logging "Not migrating, already at version {number}". Defaults to true.
    • collectionName: (string) The name of the MongoDB collection used to track migrations. Defaults to "migrations".
    Migrations.config({
  log: true,
  logger: null,
  logIfLatest: true,
  collectionName: "migrations"
});

  5. Resolve 'Not migrating, control is locked' error

    master

    If a migration fails or throws an exception, the system may set a lock to prevent multiple instances from running migrations simultaneously. If you encounter the error Not migrating, control is locked, you must manually unlock the system.

    Option 1: Via Meteor Shell

    Run Migrations.unlock(); in the Meteor shell.

    Option 2: Via Mongo Shell

    Access the database directly and update the lock status in the migrations collection:

    $ meteor mongo

db.migrations.update({_id:"control"}, {$set:{"locked":false}});
exit
    // In Meteor shell
Migrations.unlock();

  6. Implement a custom logger

    master

    You can provide a custom logger to Migrations.config(). The logger must be a function that accepts an opts object containing:

    • level: One of info, warn, error, debug.
    • message: The log message (e.g., "Finished migrating.").
    • tag: Always set to "Migrations".
    var MyLogger = function(opts) {
  console.log('Level', opts.level);
  console.log('Message', opts.message);
  console.log('Tag', opts.tag);
}

Migrations.config({
  logger: MyLogger
});

  7. Use advanced migration features (up/down, names, and reruns)

    master

    Migrations can include a name for identification and a down function to allow for rollbacks.

    Migration Directions

    • Migrations.migrateTo('latest'): Migrates to the highest version.
    • Migrations.migrateTo(number): Migrates to a specific version. The system automatically determines if it needs to go up or down.
    • Migrations.migrateTo(0): Undoes all migrations (version 0 is reserved for a 'vanilla' system).
    • Migrations.migrateTo('version,rerun'): Re-runs a specific migration version.

    Checking Version

    Use Migrations.getVersion() to see the current database version.

    Migrations.add({
  version: 1,
  name: 'Adds pants to some people in the db.',
  up: function() {//code to migrate up to version 1}
  down: function() {//code to migrate down to version 0}
});

// Migrate to version 2
Migrations.migrateTo(2);

// Re-run version 3
Migrations.migrateTo('3,rerun');

// Check current version
const currentVersion = Migrations.getVersion();