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

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,91 @@ 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.
+ */
+/**
+ * Keep the reverse operations of the steps executed on the database. The
+ * failed step only changed the database, if its main statement went through
+ * before failing, signaled by the driver (e.g. a foreign key of createTable
+ * failed after the table was created).
+ */
+const executedSteps = (internals, failed, signaled) => {
+  const done = internals.migrationDone;
+
+  internals.modSchema.s = internals.modSchema.s.filter(
+    entry =>
+      entry.n <= done || (signaled && failed > done && entry.n === failed)
+  );
+};
+
+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 +119,33 @@ 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;
+      }
+    }
+
+    context.internals.migrationDone = chain.recovery ? chain.recovery.done : 0;
 
-    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
@@ -51,15 +157,19 @@ const execUnit = {
         dbm: context.internals.safeOptions.dbmigrate
       });
     } catch (err) {
-      context.internals.rollback = true;
-
       // transfer last state
       chain.transferInt();
+      executedSteps(
+        context.internals,
+        chain.op,
+        chain.udriver._counter.previousSignal() === true
+      );
 
       log.error(
         '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 +187,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 +222,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

@@ -175,7 +175,8 @@ class STD {
       }
     }
 
-    this.modS[t] = {};
+    // keep the columns removed before from the same table
+    if (!this.modS[t]) this.modS[t] = {};
 
     if (columns[c].notNull === true && !this.unlearn) {
       switch (o.columnStrategy) {
@@ -260,7 +261,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);
     }
@@ -300,7 +301,7 @@ class STD {
 
     alter.i[t] = {};
     alter.i[t][i] = this.indizies[t][i];
-    this.modI[t] = {};
+    if (!this.modI[t]) this.modI[t] = {};
     this.modI[t][i] = this.indizies[t][i];
     delete this.indizies[t][i];
 
@@ -345,10 +346,12 @@ class STD {
 
     alter.f[t] = {};
     alter.f[t][k] = this.foreign[t][k];
-    this.modF[t] = {};
+    if (!this.modF[t]) this.modF[t] = {};
     this.modF[t][k] = this.foreign[t][k];
     delete this.foreign[t][k];
 
+    this.modC.push({ t: 1, a: 'addForeignKey', c: [t, k] });
+
     return Promise.resolve(alter);
   }
 
@@ -371,6 +374,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,18 @@
+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 () {
+        // in memory first, a failing write must not hide the executed step
+        internals.migrationDone = internals.migrationOp;
+        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

@@ -46,6 +46,11 @@ const methods = {
     return driver.changeColumn(t, c, internals.modSchema.c[t][c]);
   },
 
+  addForeignKey: async (driver, [t, k], internals) => {
+    const foreign = internals.modSchema.f[t][k];
+    return driver.addForeignKey(t, foreign.rt, k, foreign.m, foreign.r);
+  },
+
   addIndex: async (driver, [t, i], internals) => {
     if (!internals.modSchema.i[t][i]) {
       log.warn(
@@ -101,7 +106,7 @@ async function processEntry (
     }
   }
 
-  internals.modSchema.s.shift();
+  internals.modSchema.s.pop();
   await State.update(pdriver, file, internals.modSchema, internals);
 }
 
@@ -113,7 +118,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.38",
   "engines": {
     "node": ">=8.0.0"
   },