db-migrate 1.0.0-beta.36 → 1.0.0-beta.37

package/connect.js

@@ -85,7 +85,8 @@ exports.connect = async function (config, PassedClass) {
                 dirPath,
                 internals.mode !== 'static',
                 internals,
-                prefix
+                prefix,
+                { db2 }
               )
             );
           }

package/lib/chain.js

@@ -1,3 +1,5 @@
+const log = require('db-migrate-shared').log;
+
 const DEFAULT = [
   'renameCollection',
   'dropCollection',
@@ -15,6 +17,21 @@ const DEFAULT = [
   'removeForeignKey'
 ];
 
+/**
+ * Human readable form of an instruction for the log, like
+ * addColumn("users", "email")
+ */
+const describe = (method, args) =>
+  `${method}(${args
+    .filter(
+      a =>
+        typeof a === 'string' ||
+        typeof a === 'number' ||
+        (Array.isArray(a) && a.every(x => typeof x === 'string'))
+    )
+    .map(a => JSON.stringify(a))
+    .join(', ')})`;
+
 let rollbackCounter = 0;
 let rollbackSignal = null;
 let signal = null;
@@ -82,6 +99,14 @@ class Chain {
     this._step = null;
     this._interface = null;
 
+    /**
+     * op: number of the current step, the instructions of a migration
+     * recovery: progress of an interrupted previous run to resume from,
+     *           see State.startMigration
+     */
+    this.op = 0;
+    this.recovery = null;
+
     DEFAULT.concat(Object.keys(this.context.learnable || [])).forEach(
       method => {
         this[method] = function (...args) {
@@ -130,7 +155,33 @@ class Chain {
   async exec (m, ...args) {
     let ret;
     const stat = [];
+    const op = ++this.op;
+    const recovery = this.recovery;
+    this.internals.migrationOp = op;
+
+    if (recovery && op <= recovery.done) {
+      log.info(
+        `[recovery] ${this.file.name}: skipping already executed step ` +
+          `${op}/${recovery.done} ${describe(m, args)}`
+      );
+      return ret;
+    }
+
+    // the step was interrupted after its reverse operation was recorded,
+    // but before it finished on the database
+    const learned = recovery !== null && op <= recovery.learned;
+    if (learned) {
+      log.info(
+        `[recovery] ${this.file.name}: executing interrupted step ${op} ` +
+          `${describe(m, args)} without learning it again`
+      );
+    }
+
     while (this.step()) {
+      if (learned && this._step.learns) {
+        continue;
+      }
+
       ret = await this._interface[m].apply(this._interface, args);
       stat.push(ret);
 

package/lib/executors/versioned/v2.js

@@ -8,10 +8,76 @@ const Chain = require('../../chain');
 const StateTravel = require('../../methods/v2/statetravel')();
 const StateNoStepTravel = require('../../methods/v2/statetravel')(false);
 const Migrate = require('../../methods/v2/migrate');
+const StateDone = require('../../methods/v2/statedone');
 const TranslateState = require('../../methods/v2/translatestate');
 const AddConventions = require('../../methods/v2/conventions');
 const util = require('util');
 
+/**
+ * How to recover from an interrupted run of a migration, set per migration
+ * by _meta.recovery:
+ *
+ * skip: skip the steps already executed and continue with the rest
+ * rollback: revert the steps already executed and run the migration again
+ */
+const RECOVERY_MODES = ['skip', 'rollback'];
+const RECOVERY_DEFAULT = 'skip';
+
+const recoveryMode = (file, interrupted) => {
+  const name = file.name;
+  const mode = file.get()._meta.recovery || RECOVERY_DEFAULT;
+
+  if (RECOVERY_MODES.indexOf(mode) === -1) {
+    throw new Error(
+      `Invalid recovery mode "${mode}" in migration "${name}", use one of ` +
+        RECOVERY_MODES.join(', ')
+    );
+  }
+
+  if (interrupted.rollback) {
+    if (mode !== 'rollback') {
+      log.warn(
+        `[recovery] ${name}: the previous run was interrupted while rolling ` +
+          'back, continuing the rollback'
+      );
+    }
+
+    return 'rollback';
+  }
+
+  if (mode === 'skip' && interrupted.changed) {
+    throw new Error(
+      `Migration "${name}" was interrupted at step ${interrupted.step} and ` +
+        'changed since, so the executed steps can not be skipped safely. ' +
+        "Set _meta.recovery to 'rollback' to revert them, or repair the " +
+        'state manually.'
+    );
+  }
+
+  return mode;
+};
+
+/**
+ * Revert the steps executed by an interrupted run. A step started but not
+ * done did not change the database, so its reverse operation is dropped.
+ */
+const recoverByRollback = async (context, driver, file, interrupted) => {
+  const internals = context.internals;
+  const pdriver = context._pdriver;
+
+  await State.rollingBack(pdriver, internals);
+  internals.modSchema.s = internals.modSchema.s.filter(
+    entry => !(entry.n > interrupted.done)
+  );
+  await TranslateState(context._driver, file, driver, internals, pdriver);
+
+  internals.unlearn = false;
+  internals.rollback = false;
+  internals.rollbackContinue = false;
+  internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
+  await State.endMigration(pdriver, file, internals);
+};
+
 const execUnit = {
   _extend: (context, type) => {
     return {
@@ -38,8 +104,31 @@ const execUnit = {
     chain.addChain(Learn);
     chain.addChain(StateNoStepTravel);
     chain.addChain(Migrate);
+    chain.addChain(StateDone);
+
+    const interrupted = await State.startMigration(
+      context._pdriver,
+      file,
+      context.internals,
+      { recover: true }
+    );
+
+    if (interrupted) {
+      const mode = recoveryMode(file, interrupted);
+      log.warn(
+        `[recovery] ${file.name}: the previous run was interrupted at step ` +
+          `${interrupted.step}, ${interrupted.done} steps were executed, ` +
+          `recovering by ${mode}`
+      );
+
+      if (mode === 'rollback') {
+        await recoverByRollback(context, driver, file, interrupted);
+        await State.startMigration(context._pdriver, file, context.internals);
+      } else {
+        chain.recovery = interrupted;
+      }
+    }
 
-    await State.startMigration(context._pdriver, file, context.internals);
     // startMigration - needs secondary instance since we can not afford to
     // loose state and the transaction start will include these for roll back
     // we will disable them probably at all from DDL when the driver does not
@@ -60,6 +149,7 @@ const execUnit = {
         'An error occured. No alternative failure strategy defined. Rolling back!',
         err
       );
+      await State.rollingBack(context._pdriver, context.internals);
       await execUnit.down(context, driver, file, { abort: true });
       throw err;
     }
@@ -77,7 +167,9 @@ const execUnit = {
     chain.addChain(Learn);
     chain.addChain(StateTravel);
 
-    await State.startMigration(context._pdriver, file, context.internals);
+    await State.startMigration(context._pdriver, file, context.internals, {
+      op: 'fix'
+    });
     // startMigration - needs secondary instance since we can not afford to
     // loose state and the transaction start will include these for roll back
     // we will disable them probably at all from DDL when the driver does not
@@ -110,7 +202,9 @@ const execUnit = {
     // if we get the abort signal this means we are in a rollback routine
     // which means in turn we want to avoid reloading the state
     if (abort !== true) {
-      await State.startMigration(context._pdriver, file, context.internals);
+      await State.startMigration(context._pdriver, file, context.internals, {
+        op: 'down'
+      });
     }
     // start migration, see up comments
     await TranslateState(context._driver, file, driver, context.internals, context._pdriver);

package/lib/learn.js

@@ -260,7 +260,7 @@ class STD {
 
   addIndex (t, i, c, u) {
     if (Array.isArray(c)) {
-      c.forEach(x => this.checkColumn(t, typeof x  === 'object' ? x.name : x));
+      c.forEach(x => this.checkColumn(t, typeof x === 'object' ? x.name : x));
     } else {
       this.checkColumn(t, c);
     }
@@ -371,6 +371,9 @@ const noLearnError = prop => {
 };
 
 module.exports = {
+  // learns the schema and records the reverse operations
+  learns: true,
+
   getInterface: (context, file, driver, internals) => {
     if (context.learnable) {
       const _std = new STD(internals, context);

package/lib/methods/v2/statedone.js

@@ -0,0 +1,16 @@
+const Shadow = require('../../driver/shadow');
+const State = require('../../state');
+
+/**
+ * Records a step as done, after it was executed on the database.
+ */
+module.exports = {
+  getInterface: (context, file, driver, internals, pdriver) => {
+    const done = () =>
+      function () {
+        return State.done(pdriver, internals.migrationOp, internals);
+      };
+
+    return Shadow.overshadow(driver, {}, done);
+  }
+};

package/lib/methods/v2/statetravel.js

@@ -17,24 +17,38 @@ const DEFAULT = {
   removeForeignKey: 'addForeignKey'
 };
 
+/**
+ * Persists the state around learning a step. Before learning (step) it
+ * records the step as started, afterwards it tags the recorded reverse
+ * operations with their step and records the step as learned.
+ */
 class StateTravel {
   constructor (internals, file, driver, pdriver, step = true) {
     this.file = file;
     this.internals = internals;
     this.driver = driver;
     this.pdriver = pdriver;
-    this._counter = 0;
     this._default = async function _default () {
+      const op = this.internals.migrationOp;
+
       if (step) {
-        await State.step(this.pdriver, ++this._counter, this.internals);
+        await State.step(this.pdriver, op, this.internals);
+      } else {
+        this.internals.modSchema.s.forEach(entry => {
+          if (entry.n === undefined) entry.n = op;
+        });
       }
 
-      return State.update(
+      await State.update(
         this.pdriver,
         this.file,
         this.internals.modSchema,
         this.internals
       );
+
+      if (!step) {
+        await State.learned(this.pdriver, op, this.internals);
+      }
     };
   }
 }

package/lib/methods/v2/translatestate.js

@@ -101,7 +101,7 @@ async function processEntry (
     }
   }
 
-  internals.modSchema.s.shift();
+  internals.modSchema.s.pop();
   await State.update(pdriver, file, internals.modSchema, internals);
 }
 
@@ -113,7 +113,9 @@ module.exports = async (context, file, driver, internals, pdriver) => {
 
   chain.addChain(Learn);
   chain.addChain(Migrate);
-  await Promise.resolve(mod.s.reverse()).each(args =>
+  // the stored records keep their order, so an interrupted rollback can
+  // be continued
+  await Promise.resolve(mod.s.slice().reverse()).each(args =>
     processEntry(context, file, chain, internals, pdriver, args)
   );
 

package/lib/state.js

@@ -29,6 +29,21 @@ let queue = Promise.resolve();
 
 const nonce = () => crypto.randomBytes(8).toString('hex');
 
+const hashFile = async file => {
+  if (!file.path) {
+    return null;
+  }
+
+  try {
+    return crypto
+      .createHash('sha256')
+      .update(await fs.readFile(file.path))
+      .digest('hex');
+  } catch (err) {
+    return null;
+  }
+};
+
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 
 const lockOptions = internals => {
@@ -194,7 +209,9 @@ module.exports = {
       log.warn(
         `[state] taking over a stale migration lock from ${s.date}` +
           (s.fin === 0
-            ? `, the previous run was interrupted during a migration at step ${s.step}`
+            ? `, the previous run was interrupted during ${
+                s.f ? `migration "${s.f}"` : 'a migration'
+              } at step ${s.step}`
             : '')
       );
     }
@@ -334,31 +351,80 @@ module.exports = {
     }
   },
 
-  startMigration: async function (driver, file, internals) {
+  /**
+   * Start a migration in the state. With recover, an interrupted previous
+   * run of the same migration is not reset but returned, so the caller can
+   * decide how to recover:
+   *
+   * step: the last step started
+   * learned: the last step whose reverse operation was recorded
+   * done: the last step executed on the database
+   * rollback: the run was interrupted while rolling back
+   * changed: the migration file changed since
+   */
+  startMigration: async function (
+    driver,
+    file,
+    internals,
+    { op = 'up', recover = false } = {}
+  ) {
     const mig = await driver._getKV(internals.migrationState, file.name);
 
     if (mig && mig.value !== '{}') {
       internals.modSchema = JSON.parse(mig.value);
+      // records of older runs, they belong to no step of this run
+      (internals.modSchema.s || []).forEach(entry => {
+        if (entry.n === undefined) entry.n = 0;
+      });
     }
 
     if (internals.dryRun) {
-      return Promise.resolve();
+      return null;
+    }
+
+    const h = await hashFile(file);
+    const row = await read(driver, internals);
+    const prev = row ? JSON.parse(row.value).s : null;
+
+    if (prev && prev.fin === 0 && prev.f) {
+      if (recover && prev.f === file.name && prev.o === 'up' && op === 'up') {
+        return {
+          step: prev.step || 0,
+          learned: prev.learned || 0,
+          done: prev.done || 0,
+          rollback: prev.rb === 1,
+          changed: !!prev.h && !!h && prev.h !== h
+        };
+      }
+
+      log.warn(
+        `[state] ignoring the interrupted ${prev.o} of migration ` +
+          `"${prev.f}" at step ${prev.step}`
+      );
     }
 
     await module.exports.progress(driver, internals, s => {
-      s.step = 0;
-      s.fin = 0;
+      Object.assign(s, {
+        step: 0,
+        fin: 0,
+        f: file.name,
+        o: op,
+        learned: 0,
+        done: 0,
+        rb: 0,
+        h
+      });
     });
 
     if (!mig) {
-      return driver._insertKV(
+      await driver._insertKV(
         internals.migrationState,
         file.name,
         JSON.stringify({})
       );
-    } else {
-      return Promise.resolve();
     }
+
+    return null;
   },
 
   /**
@@ -412,6 +478,36 @@ module.exports = {
     return driver._getKV(internals.migrationState, file.name);
   },
 
+  learned: async function (driver, step, internals) {
+    if (internals.dryRun) {
+      return Promise.resolve();
+    }
+
+    return module.exports.progress(driver, internals, s => {
+      s.learned = step;
+    });
+  },
+
+  done: async function (driver, step, internals) {
+    if (internals.dryRun) {
+      return Promise.resolve();
+    }
+
+    return module.exports.progress(driver, internals, s => {
+      s.done = step;
+    });
+  },
+
+  rollingBack: async function (driver, internals) {
+    if (internals.dryRun) {
+      return Promise.resolve();
+    }
+
+    return module.exports.progress(driver, internals, s => {
+      s.rb = 1;
+    });
+  },
+
   step: async function (driver, step, internals) {
     log.verbose(`[state] proceeded to step ${step}`);
     if (internals.dryRun) {
@@ -435,6 +531,7 @@ module.exports = {
     // the lock itself stays until the walker releases it
     return module.exports.progress(driver, internals, s => {
       s.fin = 1;
+      s.rb = 0;
     });
   }
 };

package/package.json

@@ -31,7 +31,7 @@
     "programable",
     "api"
   ],
-  "version": "1.0.0-beta.36",
+  "version": "1.0.0-beta.37",
   "engines": {
     "node": ">=8.0.0"
   },