RFC #5 - New Migration Schema

[wzrdtales]

Foreword

This RFC describes the new migration schema, which is needed to better support safe migrations. This will solve problems that currently exists with:

• Rollbacks of actions within migrations
• Continuation of aborted migrations (i.e. when the server was crashing while executing)
• Zero Downtime compatible operations

Requirements

It is required to have any action, an action will describe as a single operation like renameColumn, within a migration directly linked with its reversion. An action may in some occassions be of a deterministic nature and directly revertable without further description of the rollback routine.

Backwards Compatibility

There is no need to keep compatible to any old migration schema, as migration schemas are excplicitly versioned by their _meta export. However, drivers may not be affected and should not have the need to change.

Effects on issues

This RFC will have effects on the following issues:

• Question: Is execution of multiple migrations atomic? #410
• Modernize the syntax in new migration files #383

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[wzrdtales]

Referencing some recent commenters for opinions @BorntraegerMarc @GeeWee @westy92 @RemyJeancolas

[wzrdtales]

A first suggestion might be something like this:

First naive attempt

On completely deterministic components ending up as easy as this:

exports.migrate = db => {
   return db.createTable('table1', { imagineoptions: 'here' }); // this is it, we know the reverse of createTable which always is dropTable
}

On non deterministic components:

exports.migrate = async db => {
  await db.dropTable('table1')
    .reverse(() => db.createTable('table1', { imagineoptions: 'here' });

  return db.someOtherAction());
}

Question here would be, are we explicitlly enforcing to provide a reverse.

Second attempt, maybe better?

And currently it seems to me like this wouldn't be that readable, so probably the first naive, but not perferct attempt. May be it should look something more like this:

exports.migrate = async db => {
  await db.atomic({
      up: db.dropTable('table1'),
      down: db.db.createTable('table1', { imagineoptions: 'here' })
  });
    
  return db.someOtherAction();
}

Chances to clean up and get rid of old stuff

Also a chance to get rid of setup, including them as second parameter as options:

exports.migrate = async (db, dbm) => {
  await db.driverDoesStuff();
  console.log(dbm); // all that informational or additional stuff
  return null;
}

Also to note, that I would still keep callbacks as an option to use here, but would not document it anywhere, so that promises and async/await emerge to be the default schema to work in and not supporting callbacks anymore officially.

[wzrdtales]

To note the final version would be the official version 2 of the migrations schema.

[wzrdtales]

Referencing driver devs as well @charyorde @Yashin32 @etops

[wzrdtales]

Oh forgot @toymachiner62

[wtgtybhertgeghgtwtg]

Since the code samples are using async, are you planning on bumping the required node version or using babel? It would certainly help simplify the codebase.

[wzrdtales]

@wtgtybhertgeghgtwtg Yes and no. I will never use babel, but I will definitely drop backwards support to the most outdated versions. Current plan is down to node 4.

[wzrdtales]

Looking at the distribution of node versions though. People are currently only starting to move over the new LTS though. It is a bit to early to also drop node 4.