Creating Migrations

You can use the Formn CLI to generate a migration template script using the create sub-command. Just supply a name for the migration script and Formn will generate a migration template for you. We’ll create and run some migrations in the next sections, but first let’s go over the basics.

The Anatomy of a Migration Script

When you create a migration script, the script’s name will be prefixed with a timestamp. The timestamp is informative in that it tells the developer when each migration was created and in what order. The naming convention is also important internally: it’s how Formn knows the order in which migrations should be run.

A migration script is a plain old JavaScript file with two methods exported: up and down. The former brings a database up to date; the latter is the inverse and reverses a migration. So if, for example, the up method creates a table, the down method should drop the table.

Both methods take a single argument: a connected DataContext instance (see the DataContext section). Both methods should return a Promise instance. You also can make the methods async. (An async method implicitly returns a Promise.)

Behind the scenes, the Formn CLI creates a formn_migrations table. This table is used to track the migrations that have been run. The table is trivial, and includes the name of each migration and a timestamp that shows when the migration was run.

The Migration Template

When you create a migration, the generated template will look as follows.

'use strict';

module.exports = {
  /**
   * Run the migration.
   */
  up(dataContext) {
    const sql    = ``;
    const params = {};

    console.log(sql);

    return dataContext
      .getExecuter()
      .query(sql, params); 
  },

  /**
   * Bring down a migration.
   */
  down(dataContext) {
    const sql    = ``;
    const params = {};

    console.log(sql);

    return dataContext
      .getExecuter()
      .query(sql, params); 
  }
};

Just add SQL strings and any parameters as needed, and return a Promise.

Next up we’ll dive into some examples.