db-migrate 1.0.0-beta.35 → 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/commands/set-default-argv.js

@@ -17,7 +17,9 @@ module.exports = function (internals, isModule) {
     'vcseeder-dir': internals.cwd + '/VCSeeder',
     'staticseeder-dir': internals.cwd + '/Seeder',
     'ignore-completed-migrations': false,
-    'backup-state': false
+    'backup-state': false,
+    'lock-timeout': 60000,
+    'lock-interval': 1000
   };
 
   if (!isModule) {
@@ -116,6 +118,17 @@ module.exports = function (internals, isModule) {
       .string('log-level')
       .describe('backup-state', 'For use with fix, to take a backup of the current state before continuing.')
       .boolean('backup-state')
+      .describe(
+        'lock-timeout',
+        'Milliseconds without any sign of life after which a migration lock' +
+          ' held by another process is considered stale and taken over.'
+      )
+      .number('lock-timeout')
+      .describe(
+        'lock-interval',
+        'Milliseconds between checks while waiting for the migration lock.'
+      )
+      .number('lock-interval')
       .parse();
   } else {
     internals.argv = Object.assign(defaultConfig, internals.cmdOptions);

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

@@ -1,68 +1,301 @@
 const MSTATE = '__dbmigrate_state__';
 const SSTATE = '__dbmigrate_schema__';
-const RUNON = 'run_on';
 
 const log = require('db-migrate-shared').log;
 const fs = require('fs').promises;
 const path = require('path');
 const crypto = require('crypto');
+const { performance } = require('perf_hooks');
 
 const ID = crypto.randomBytes(32).toString('base64');
+
+const LOCK_TIMEOUT = 60000;
+const LOCK_INTERVAL = 1000;
+
+/**
+ * active: a lock session is running, from acquire until release, even if
+ *         the lock got lost in between
+ * owner: we currently hold the lock
+ * current: the last MSTATE row we wrote and verified, the expected
+ *          value for our next compare and swap
+ * queue: serializes our own writes, so heartbeat and state updates
+ *        never race each other on the same expected row
+ */
+let active = false;
 let owner = false;
+let current = null;
+let heartbeat = null;
+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 => {
+  const argv = internals.argv || {};
+  return {
+    timeout: Number(argv['lock-timeout']) || LOCK_TIMEOUT,
+    interval: Number(argv['lock-interval']) || LOCK_INTERVAL
+  };
+};
+
+const read = (driver, internals) =>
+  driver._getKV(internals.migrationState, MSTATE);
+
+const holder = row => JSON.parse(row.value).s.ID;
+
+const heldByOther = row => {
+  const id = holder(row);
+  return !!id && id !== ID;
+};
+
+/**
+ * Atomic update of the lock row. The where clause contains the value we
+ * have read before, which carries the date and a nonce renewed on every
+ * write. If anybody else wrote in between, the update matches no row.
+ * Whoever wins, sees his own value on re-read.
+ */
+const cas = (driver, internals, expected, value) =>
+  driver._updateKVC(
+    internals.migrationState,
+    MSTATE,
+    value,
+    'value',
+    expected.value
+  );
+
+/**
+ * Concurrent CREATE TABLE IF NOT EXISTS can still collide (e.g. on pg_type
+ * in postgres) when several processes start on an empty database. The
+ * second attempt finds the table and is a noop.
+ */
+const createConcurrently = async create => {
+  try {
+    await create();
+  } catch (err) {
+    log.verbose('[state] create failed, retrying once', err.message);
+    await create();
+  }
+};
+
+/**
+ * The stored schema starts as '{}', keep the structure the walker expects.
+ */
+const parseSchema = value =>
+  Object.assign({ i: {}, c: {}, f: {}, e: {} }, JSON.parse(value));
+
+const stopHeartbeat = () => {
+  if (heartbeat) {
+    clearInterval(heartbeat);
+    heartbeat = null;
+  }
+};
+
+const write = (driver, internals, mutate) => {
+  const run = queue.then(async () => {
+    if (!owner) {
+      throw new Error('[state] the migration lock is not held by this process');
+    }
+
+    const state = JSON.parse(current.value);
+    Object.assign(state.s, { ID, date: new Date(), n: nonce() });
+    mutate(state.s);
+
+    const value = JSON.stringify(state);
+    await cas(driver, internals, current, value);
+    const row = await read(driver, internals);
+
+    if (!row || row.value !== value) {
+      owner = false;
+      current = null;
+      stopHeartbeat();
+      throw new Error('[state] lost the migration lock to another process');
+    }
+
+    current = row;
+  });
+
+  queue = run.catch(() => {});
+  return run;
+};
+
+const claim = (row, driver, internals) => {
+  if (!row || holder(row) !== ID) {
+    return false;
+  }
+
+  active = true;
+  owner = true;
+  current = row;
+
+  const { timeout } = lockOptions(internals);
+  heartbeat = setInterval(() => {
+    write(driver, internals, () => {}).catch(err => log.error(err.message));
+  }, Math.max(Math.floor(timeout / 3), 1));
+  heartbeat.unref();
+
+  return true;
+};
 
 module.exports = {
+  createConcurrently,
+
+  // for tests, simulates a process which died while holding the lock
+  __stopHeartbeat: stopHeartbeat,
+
   /**
-   * Lock state will add the basic state controller an ID
-   * and a process controlled date.
-   * It is important that all systems are in sync. We will use the
-   * database clock instead if possible.
+   * Drivers declare that their state methods were verified for locking,
+   * with an atomic _updateKVC and run_on set by the database clock.
    */
-  lockState: async function (driver, state, internals) {
-    if (!state) {
-      owner = true;
-      return driver._insertKV(
-        internals.migrationState,
-        MSTATE,
-        JSON.stringify({
-          s: {
-            step: 0,
-            fin: 0,
-            ID,
-            date: new Date()
-          }
-        })
-      );
-    } else {
-      let runOn = state.run_on;
-      state = state.value;
-      state = JSON.parse(state);
-
-      if (!state.s.ID || state.s.ID !== ID) {
-        owner = true;
-        state.s.ID = ID;
+  supportsLock: function (driver) {
+    return !!(
+      driver &&
+      driver._meta &&
+      driver._meta.supports &&
+      driver._meta.supports.locking === true
+    );
+  },
+
+  /**
+   * Try to acquire the migration lock once. Resolves to true if this process
+   * is the owner afterwards. A lock held by another process is only taken
+   * over, if it is the exact row waitForRelease reported as stale.
+   */
+  acquire: async function (driver, internals, stale = null, retries = 3) {
+    if (owner) {
+      return true;
+    }
+
+    const row = await read(driver, internals);
+
+    if (!row) {
+      try {
+        await driver._insertKV(
+          internals.migrationState,
+          MSTATE,
+          JSON.stringify({
+            s: { step: 0, fin: 1, ID, date: new Date(), n: nonce() }
+          })
+        );
+      } catch (err) {
+        // somebody else inserted the row first, the re-read decides
+        log.verbose('[state] lock insert failed', err.message);
       }
 
-      const d = new Date();
+      return claim(await read(driver, internals), driver, internals);
+    }
 
-      state.s.date = d;
-      await driver._updateKVC(
-        internals.migrationState,
-        MSTATE,
-        JSON.stringify(state),
-        RUNON,
-        runOn
+    if (heldByOther(row)) {
+      if (!stale || stale.value !== row.value) {
+        return false;
+      }
+
+      const { s } = JSON.parse(row.value);
+      log.warn(
+        `[state] taking over a stale migration lock from ${s.date}` +
+          (s.fin === 0
+            ? `, the previous run was interrupted during ${
+                s.f ? `migration "${s.f}"` : 'a migration'
+              } at step ${s.step}`
+            : '')
       );
+    }
 
-      state = await driver._getKV(internals.migrationState, MSTATE);
+    const state = JSON.parse(row.value);
+    Object.assign(state.s, { ID, date: new Date(), n: nonce() });
+    await cas(driver, internals, row, JSON.stringify(state));
 
-      runOn = state.run_on;
-      state = state.value;
-      state = JSON.parse(state);
+    const after = await read(driver, internals);
+    if (claim(after, driver, internals)) {
+      return true;
+    }
 
-      if (state.s.ID !== ID) {
-        owner = false;
+    // Nobody holds the lock, still our update did not apply. Either another
+    // process acquired and released in between, or the compare and swap does
+    // not work with this driver at all, which must not end in a busy loop.
+    if (after && !heldByOther(after)) {
+      if (retries > 0) {
+        return module.exports.acquire(driver, internals, null, retries - 1);
       }
+
+      throw new Error(
+        '[state] could not acquire the migration lock although it is free, ' +
+          'the driver does not seem to support compare and swap on the state'
+      );
+    }
+
+    return false;
+  },
+
+  /**
+   * Wait until the lock is released. A lock whose row did not change for
+   * lock-timeout ms is considered stale, its holder is gone. This is
+   * measured on our own monotonic clock, so no clocks have to be in sync.
+   *
+   * Resolves to the stale row, or null if the lock was released properly.
+   */
+  waitForRelease: async function (driver, internals) {
+    const { timeout, interval } = lockOptions(internals);
+    let seen = null;
+    let since = 0;
+
+    for (;;) {
+      const row = await read(driver, internals);
+
+      if (!row || !heldByOther(row)) {
+        return null;
+      }
+
+      const now = performance.now();
+      if (
+        !seen ||
+        seen.value !== row.value ||
+        String(seen.run_on) !== String(row.run_on)
+      ) {
+        seen = row;
+        since = now;
+      } else if (now - since >= timeout) {
+        return row;
+      }
+
+      await delay(interval);
+    }
+  },
+
+  release: async function (driver, internals) {
+    stopHeartbeat();
+
+    if (!owner) {
+      active = false;
+      return;
     }
+
+    try {
+      await write(driver, internals, s => {
+        s.ID = 0;
+      });
+    } catch (err) {
+      log.warn(err.message);
+    }
+
+    active = false;
+    owner = false;
+    current = null;
   },
 
   isOwner: function () {
@@ -70,7 +303,7 @@ module.exports = {
   },
 
   init: async function (driver, internals, { emptyState, backupState }) {
-    await driver._createKV(internals.migrationState);
+    await createConcurrently(() => driver._createKV(internals.migrationState));
     const _schema = await driver._getKV(internals.migrationState, SSTATE);
 
     if (_schema && backupState) {
@@ -91,42 +324,139 @@ module.exports = {
 
     const schema = emptyState !== true ? _schema : null;
     if (schema) {
-      internals.schema = JSON.parse(schema.value);
+      internals.schema = parseSchema(schema.value);
     } else if (!emptyState) {
-      await driver._insertKV(internals.migrationState, SSTATE, '{}');
+      try {
+        await driver._insertKV(internals.migrationState, SSTATE, '{}');
+      } catch (err) {
+        // another process initialized the state at the same time
+        const row = await driver._getKV(internals.migrationState, SSTATE);
+        if (!row) {
+          throw err;
+        }
+
+        internals.schema = parseSchema(row.value);
+      }
     }
+  },
 
-    if (!internals.dryRun) {
-      const state = await driver._getKV(internals.migrationState, MSTATE);
-      return module.exports.lockState(driver, state, internals);
+  /**
+   * Another process may have migrated while we were waiting for the lock,
+   * so the schema loaded during init is outdated.
+   */
+  reloadSchema: async function (driver, internals) {
+    const schema = await driver._getKV(internals.migrationState, SSTATE);
+    if (schema) {
+      internals.schema = parseSchema(schema.value);
     }
-
-    return Promise.resolve();
   },
 
-  startMigration: async function (driver, file, internals) {
-    const state = await driver._getKV(internals.migrationState, MSTATE);
+  /**
+   * 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;
     }
 
-    await module.exports.lockState(driver, state, internals);
+    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 => {
+      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;
+  },
+
+  /**
+   * Write migration progress into the lock row. While holding the lock this
+   * is a compare and swap, which fails if we lost the lock. Without a lock
+   * (driver does not support it) the row is written unconditionally.
+   */
+  progress: async function (driver, internals, mutate) {
+    if (active) {
+      return write(driver, internals, mutate);
+    }
+
+    const row = await read(driver, internals);
+    const state = row
+      ? JSON.parse(row.value)
+      : { s: { step: 0, fin: 0, ID: 0 } };
+    state.s.date = new Date();
+    mutate(state.s);
+
+    if (!row) {
+      return driver._insertKV(
+        internals.migrationState,
+        MSTATE,
+        JSON.stringify(state)
+      );
+    }
+
+    return driver._updateKV(
+      internals.migrationState,
+      MSTATE,
+      JSON.stringify(state)
+    );
   },
 
   update: async function (driver, file, state, internals) {
@@ -148,45 +478,34 @@ module.exports = {
     return driver._getKV(internals.migrationState, file.name);
   },
 
-  tick: async function (driver, internals) {
+  learned: async function (driver, step, internals) {
     if (internals.dryRun) {
       return Promise.resolve();
     }
 
-    let state = await driver._getKV(
-      internals.migrationState,
-      MSTATE
-    );
-
-    let runOn = state.run_on;
-    state = state.value;
-    state = JSON.parse(state);
+    return module.exports.progress(driver, internals, s => {
+      s.learned = step;
+    });
+  },
 
-    if (!state.s.ID || state.s.ID !== ID) {
-      owner = true;
-      state.s.ID = ID;
+  done: async function (driver, step, internals) {
+    if (internals.dryRun) {
+      return Promise.resolve();
     }
 
-    const d = new Date();
-
-    state.s.date = d;
-    await driver._updateKVC(
-      internals.migrationState,
-      MSTATE,
-      JSON.stringify(state),
-      RUNON,
-      runOn
-    );
-
-    state = await driver._getKV(internals.migrationState, MSTATE);
-
-    runOn = state.run_on;
-    state = state.value;
-    state = JSON.parse(state);
+    return module.exports.progress(driver, internals, s => {
+      s.done = step;
+    });
+  },
 
-    if (state.s.ID !== ID) {
-      owner = false;
+  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) {
@@ -195,18 +514,9 @@ module.exports = {
       return Promise.resolve();
     }
 
-    let { value: state } = await driver._getKV(
-      internals.migrationState,
-      MSTATE
-    );
-    state = JSON.parse(state);
-    state.s.date = new Date();
-    state.s.step = step;
-    return driver._updateKV(
-      internals.migrationState,
-      MSTATE,
-      JSON.stringify(state)
-    );
+    return module.exports.progress(driver, internals, s => {
+      s.step = step;
+    });
   },
 
   deleteState: function (driver, file, internals) {
@@ -218,21 +528,10 @@ module.exports = {
       return Promise.resolve();
     }
 
-    let { value: state } = await driver._getKV(
-      internals.migrationState,
-      MSTATE
-    );
-    state = JSON.parse(state);
-    state.s.date = new Date();
-    state.s.fin = 1;
-
-    // unlock from current process
-    state.s.ID = 0;
-
-    return driver._updateKV(
-      internals.migrationState,
-      MSTATE,
-      JSON.stringify(state)
-    );
+    // the lock itself stays until the walker releases it
+    return module.exports.progress(driver, internals, s => {
+      s.fin = 1;
+      s.rb = 0;
+    });
   }
 };

package/lib/walker.js

@@ -63,7 +63,9 @@ const Walker = function (driver, directory, mode, intern, prefix, opts = {}) {
 Walker.prototype = {
   createTables: async function (options) {
     await State.init(this._pdriver, this.internals, options);
-    return this._driver._createList(this.internals.migrationTable);
+    return State.createConcurrently(() =>
+      this._driver._createList(this.internals.migrationTable)
+    );
   },
 
   createMigrationsTable: function (options = {}) {
@@ -90,6 +92,52 @@ Walker.prototype = {
     return this.createTables(options);
   },
 
+  /**
+   * Determine what to run first, only lock when there is actually something
+   * to run. If another process holds the lock, wait for its release and
+   * determine again, the other process might have done the work already.
+   * Once we hold the lock, state and pending migrations are read again.
+   */
+  _withLock: async function (determine, run) {
+    if (this.prefix !== 'migration' || this.internals.dryRun) {
+      return run(await determine());
+    }
+
+    if (!State.supportsLock(this._pdriver)) {
+      log.warn(
+        this.title +
+          'Your database driver does not support migration locking, ' +
+          'concurrent processes are not prevented from migrating at the ' +
+          'same time. Update your driver to a version supporting it.'
+      );
+      return run(await determine());
+    }
+
+    let stale = null;
+    let toRun = await determine();
+
+    while (toRun.length > 0) {
+      if (await State.acquire(this._pdriver, this.internals, stale)) {
+        break;
+      }
+
+      log.info(this.title + 'Waiting for the migration lock of another process');
+      stale = await State.waitForRelease(this._pdriver, this.internals);
+      toRun = await determine();
+    }
+
+    if (toRun.length === 0) {
+      return run(toRun);
+    }
+
+    try {
+      await State.reloadSchema(this._pdriver, this.internals);
+      return await run(await determine());
+    } finally {
+      await State.release(this._pdriver, this.internals);
+    }
+  },
+
   writeMigrationRecord: function (migration, callback) {
     const onComplete = err => {
       if (err) {
@@ -149,96 +197,84 @@ Walker.prototype = {
   up: function (options, callback) {
     const partialName = options.destination;
     const count = options.count;
-    const files = Promise.all([
-      File.loadFromFileystem(this.directory, this.prefix, this.internals),
-      File.loadFromDatabase(
-        this.directory,
-        this.prefix,
-        this._driver,
-        this.internals
-      )
-    ]).spread((allFiles, completedFiles) => {
-      const toRun = dbmUtil.filterUp(
-        allFiles,
-        completedFiles,
-        partialName,
-        count
+    const determine = () =>
+      Promise.all([
+        File.loadFromFileystem(this.directory, this.prefix, this.internals),
+        File.loadFromDatabase(
+          this.directory,
+          this.prefix,
+          this._driver,
+          this.internals
+        )
+      ]).spread((allFiles, completedFiles) =>
+        dbmUtil.filterUp(allFiles, completedFiles, partialName, count)
       );
 
-      if (toRun.length === 0) {
-        log.info(this.title + 'Nothing to run');
-      }
-
-      if (this.internals.check) {
-        const toRunNames = toRun.map(migration => migration.name);
-        log.info(this.title + 'run:', toRunNames);
-        return toRunNames;
-      }
-
-      return toRun;
-    });
-
     if (this.internals.check) {
-      return files.nodeify(callback);
+      return determine()
+        .then(toRun => this._checkResult(toRun))
+        .nodeify(callback);
     }
 
-    return files
-      .each(file => {
-        log.verbose(this.title + 'preparing to run up:', file.name);
-        const _meta = file.get()._meta || {};
-        const version = _meta.version || 1;
-        this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
-        return require(`./executors/versioned/v${version}`).up(
-          this,
-          this.driver,
-          file
-        );
+    return Promise.resolve(
+      this._withLock(determine, toRun => {
+        if (toRun.length === 0) {
+          log.info(this.title + 'Nothing to run');
+        }
+
+        return Promise.each(toRun, file => {
+          log.verbose(this.title + 'preparing to run up:', file.name);
+          const _meta = file.get()._meta || {};
+          const version = _meta.version || 1;
+          this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
+          return require(`./executors/versioned/v${version}`).up(
+            this,
+            this.driver,
+            file
+          );
+        });
       })
-      .nodeify(callback);
+    ).nodeify(callback);
   },
 
   down: function (options, callback) {
     const partialName = options.destination;
     const count = options.count;
-
-    const files = File.loadFromDatabase(
-      this.directory,
-      this.prefix,
-      this._driver,
-      this.internals
-    ).then(completedFiles => {
-      const toRun = dbmUtil.filterDown(completedFiles, partialName, count);
-
-      if (toRun.length === 0) {
-        log.info(this.title + 'Nothing to run');
-      }
-
-      if (this.internals.check) {
-        const toRunNames = toRun.map(migration => migration.name);
-        log.info(this.title + 'run:', toRunNames);
-        return toRunNames;
-      }
-
-      return toRun;
-    });
+    const determine = () =>
+      File.loadFromDatabase(
+        this.directory,
+        this.prefix,
+        this._driver,
+        this.internals
+      ).then(completedFiles =>
+        dbmUtil.filterDown(completedFiles, partialName, count)
+      );
 
     if (this.internals.check) {
-      return files.nodeify(callback);
+      return determine()
+        .then(toRun => this._checkResult(toRun))
+        .nodeify(callback);
     }
 
-    return files
-      .each(file => {
-        log.verbose(this.title + 'preparing to run down:', file.name);
-        const _meta = file.get()._meta || {};
-        const version = _meta.version || 1;
-        this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
-        return require(`./executors/versioned/v${version}`).down(
-          this,
-          this.driver,
-          file
-        );
+    return Promise.resolve(
+      this._withLock(determine, toRun => {
+        if (toRun.length === 0) {
+          log.info(this.title + 'Nothing to run');
+        }
+
+        return Promise.each(toRun, file => {
+          log.verbose(this.title + 'preparing to run down:', file.name);
+          const _meta = file.get()._meta || {};
+          const version = _meta.version || 1;
+          this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
+          return require(`./executors/versioned/v${version}`).down(
+            this,
+            this.driver,
+            file
+          );
+        });
       })
-      .nodeify(callback);
+    ).nodeify(callback);
   },
 
   fix: function (options, callback) {
@@ -255,49 +291,56 @@ Walker.prototype = {
       return a.localeCompare(b);
     };
 
-    const files = File.loadFromDatabase(
-      this.directory,
-      this.prefix,
-      this._driver,
-      this.internals
-    ).then(completedFiles => {
-      const toRun = dbmUtil.filterDown(completedFiles, partialName, count).sort(sortFn);
-
-      if (toRun.length === 0) {
-        log.info(this.title + 'Nothing to run');
-      }
-
-      if (this.internals.check) {
-        const toRunNames = toRun.map(migration => migration.name);
-        log.info(this.title + 'run:', toRunNames);
-        return toRunNames;
-      }
-
-      return toRun;
-    });
+    const determine = () =>
+      File.loadFromDatabase(
+        this.directory,
+        this.prefix,
+        this._driver,
+        this.internals
+      ).then(completedFiles =>
+        dbmUtil.filterDown(completedFiles, partialName, count).sort(sortFn)
+      );
 
     if (this.internals.check) {
-      return files.nodeify(callback);
+      return determine()
+        .then(toRun => this._checkResult(toRun))
+        .nodeify(callback);
     }
 
-    return files
-      .each(file => {
-        log.verbose(this.title + 'preparing to run fix:', file.name);
-        const _meta = file.get()._meta || {};
-        const version = _meta.version || 1;
-        if (version < 2) {
-          log.warn(`${this.title} skipping "${file.name}" as v1 migrations do not maintain a schema`);
-          return Promise.resolve();
+    return Promise.resolve(
+      this._withLock(determine, toRun => {
+        if (toRun.length === 0) {
+          log.info(this.title + 'Nothing to run');
         }
 
-        this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
-        return require(`./executors/versioned/v${version}`).fix(
-          this,
-          this.driver,
-          file
-        );
+        return Promise.each(toRun, file => {
+          log.verbose(this.title + 'preparing to run fix:', file.name);
+          const _meta = file.get()._meta || {};
+          const version = _meta.version || 1;
+          if (version < 2) {
+            log.warn(`${this.title} skipping "${file.name}" as v1 migrations do not maintain a schema`);
+            return Promise.resolve();
+          }
+
+          this.internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
+          return require(`./executors/versioned/v${version}`).fix(
+            this,
+            this.driver,
+            file
+          );
+        });
       })
-      .nodeify(callback);
+    ).nodeify(callback);
+  },
+
+  _checkResult: function (toRun) {
+    if (toRun.length === 0) {
+      log.info(this.title + 'Nothing to run');
+    }
+
+    const toRunNames = toRun.map(migration => migration.name);
+    log.info(this.title + 'run:', toRunNames);
+    return toRunNames;
   },
 
   check: function (options, callback) {

package/package.json

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

package/tttt.js

@@ -1,2 +0,0 @@
-
-