db-migrate 1.3.0 → 1.4.0

package/lib/dml.js

@@ -16,15 +16,22 @@ const { recoveryMode, describeFailure } = require('./recovery');
  *         first, reverting restores them from there. The rows are then
  *         changed in batches by their key, the progress is kept in the
  *         state, so an interrupted run continues where it stopped.
+ * delete in soft mode: the rows are not deleted, but get a timestamp in a
+ *         column of the user and a mark in their flag, reverting removes
+ *         both again. purge deletes such rows for good.
  * runSql: reverted by the SQL given with { revert }
  *
- * The records are { t: 4, a: action, c: args }, or { t: 3 } for a step run
- * with { irreversible: true }, which can not be reverted.
+ * Each step, and each batch of a step, runs inside a transaction, unless
+ * the migration opts out with _meta.transactions = false.
+ *
+ * The records are { t: 4, a: action, c: args }, or { t: 3 } for a step which
+ * can not be reverted, run with { irreversible: true } or a purge.
  */
 
 const FLAG = '__dbmigrate__flag';
 const BATCH = 1000;
 const TYPES = ['dml'];
+const PG = ['pg', 'cockroachdb', 'postgres', 'postgresql'];
 
 const SCHEMA_INSTRUCTIONS = [
   'createTable',
@@ -43,10 +50,14 @@ const SCHEMA_INSTRUCTIONS = [
   'renameCollection'
 ];
 
-const isDml = file => (file.get()._meta || {}).type === 'dml';
+const meta = file => file.get()._meta || {};
+
+const isDml = file => meta(file).type === 'dml';
+
+const isBackground = file => isDml(file) && meta(file).background === true;
 
 const checkType = file => {
-  const type = (file.get()._meta || {}).type;
+  const { type, background } = meta(file);
 
   if (type !== undefined && TYPES.indexOf(type) === -1) {
     throw new Error(
@@ -55,8 +66,27 @@ const checkType = file => {
         ' or leave it out for a schema migration'
     );
   }
+
+  if (background === true && type !== 'dml') {
+    throw new Error(
+      `Migration "${file.name}" runs in the background, which only dml ` +
+        "migrations can, set _meta.type to 'dml'"
+    );
+  }
 };
 
+/**
+ * Stops a worker between two batches, the job is continued later.
+ */
+class Stopped extends Error {
+  constructor () {
+    super('stopped');
+    this.stopped = true;
+  }
+}
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
 const backupName = (file, op) =>
   '__dbm_backup_' +
   crypto
@@ -65,6 +95,12 @@ const backupName = (file, op) =>
     .digest('hex')
     .slice(0, 16);
 
+// the mark of a soft delete in the flag of a row
+const deleted = (file, op) => `|del:${file.name}#${op}`;
+
+// a LIKE pattern matching text literally, with ! as escape character
+const like = text => text.replace(/[!%_]/g, c => '!' + c);
+
 const isObject = x =>
   x !== null &&
   typeof x === 'object' &&
@@ -136,13 +172,31 @@ const insertRows = args => {
   throw new Error('insert needs the rows to insert');
 };
 
+/**
+ * The progress of a migration run in the foreground is kept in the row of
+ * the migration lock, see State.
+ */
+const foreground = (pdriver, internals) => ({
+  step: op => State.step(pdriver, op, internals),
+  learned: op => State.learned(pdriver, op, internals),
+  done: op => State.done(pdriver, op, internals)
+});
+
 class Dml {
-  constructor (context, file, internals, pdriver, recovery) {
+  /**
+   * progress: records the steps started, learned and done
+   * work: options of a background worker, batch and pause between batches,
+   *       stopping() tells to stop after the current batch
+   */
+  constructor (context, file, internals, pdriver, recovery, progress, work = {}) {
     this.driver = context._driver;
     this.file = file;
     this.internals = internals;
     this.pdriver = pdriver;
     this.recovery = recovery;
+    this.progress = progress || foreground(pdriver, internals);
+    this.work = work;
+    this.transactional = meta(file).transactions !== false;
     this.op = 0;
     this.current = null;
 
@@ -165,6 +219,78 @@ class Dml {
     return t ? t.columns || t : null;
   }
 
+  /**
+   * Reads rows with parameters written as ?, all of pg takes $1, $2, ...
+   */
+  select (sql, params = []) {
+    if (!params.length) {
+      return this.driver.all(sql);
+    }
+
+    if (PG.indexOf(this.driver._dbmDriver) !== -1) {
+      let i = 0;
+      sql = sql.replace(/\?/g, () => `$${++i}`);
+    }
+
+    // with a callback, all of db-migrate-sqlite3 before 1.2.1 drops the
+    // parameters without one
+    return Promise.fromCallback(cb => this.driver.all(sql, params, cb));
+  }
+
+  /**
+   * sql followed by a text parameter. CONCAT of PostgreSQL can not tell the
+   * type of a parameter, || of MySQL is OR.
+   */
+  concat (sql) {
+    return this.driver._dbmDriver === 'mysql'
+      ? `CONCAT(${sql}, ?)`
+      : `(${sql} || CAST(? AS TEXT))`;
+  }
+
+  /**
+   * Runs fn inside a transaction, rolled back if it fails.
+   */
+  async tx (fn) {
+    if (!this.transactional || this.internals.dryRun) {
+      return fn();
+    }
+
+    await this.driver.runSql('BEGIN');
+
+    let ret;
+    try {
+      ret = await fn();
+    } catch (err) {
+      try {
+        await this.driver.runSql('ROLLBACK');
+      } catch (rollbackErr) {
+        log.verbose('[dml] rollback failed', rollbackErr.message);
+      }
+
+      throw err;
+    }
+
+    await this.driver.runSql('COMMIT');
+    return ret;
+  }
+
+  /**
+   * Between batches, a worker in the background pauses and stops if asked.
+   */
+  async between () {
+    if (this.work.stopping && this.work.stopping()) {
+      throw new Stopped();
+    }
+
+    if (this.work.pause) {
+      await delay(this.work.pause);
+    }
+  }
+
+  batchSize (options) {
+    return Number(options.batch) || Number(this.work.batch) || BATCH;
+  }
+
   /**
    * The key of a table, to change and restore its rows by. Taken from the
    * schema, for other tables it is passed with { key }.
@@ -179,10 +305,12 @@ class Dml {
 
     if (!key.length) {
       throw new Error(
-        `${action}("${table}") needs the primary key of "${table}" to revert ` +
-          'it, which is unknown to the schema of db-migrate. Pass it with ' +
-          "{ key: 'id' }, or pass { irreversible: true } to change the rows " +
-          'without being able to revert it.'
+        `${action}("${table}") needs the primary key of "${table}", which is ` +
+          "unknown to the schema of db-migrate. Pass it with { key: 'id' }" +
+          (action === 'purge'
+            ? '.'
+            : ', or pass { irreversible: true } to change the rows without ' +
+              'being able to revert it.')
       );
     }
 
@@ -251,6 +379,31 @@ class Dml {
     return { sql, params };
   }
 
+  /**
+   * Changes the rows matching condition in batches by their key, until none
+   * matches anymore. Changing a row has to make it stop matching, so this
+   * continues by itself after an interruption.
+   */
+  async untilDone (table, key, condition, options, change) {
+    const size = this.batchSize(options);
+    const order = key.map(k => this.ddl(k)).join(', ');
+
+    for (;;) {
+      const rows = await this.select(
+        `SELECT ${order} FROM ${this.ddl(table)} WHERE ${condition.sql} ` +
+          `ORDER BY ${order} LIMIT ${size}`,
+        condition.params
+      );
+
+      if (!rows.length) {
+        return;
+      }
+
+      await this.tx(() => change(this.byKey(rows, key)));
+      await this.between();
+    }
+  }
+
   /**
    * Runs one instruction as a step: records what reverts it, executes it and
    * records it as done. The step of an interrupted run is continued, with
@@ -272,7 +425,7 @@ class Dml {
       return;
     }
 
-    await State.step(this.pdriver, op, internals);
+    await this.progress.step(op);
 
     let entry = recovery && op <= recovery.learned
       ? mod.s.find(e => e.n === op)
@@ -288,22 +441,29 @@ class Dml {
       entry = record(op);
       entry.n = op;
       mod.s.push(entry);
-      await State.update(this.pdriver, this.file, mod, internals);
-      await State.learned(this.pdriver, op, internals);
+      await this.save();
+      await this.progress.learned(op);
     }
 
     await execute(entry, op);
 
     internals.migrationDone = op;
-    await State.done(this.pdriver, op, internals);
+    await this.progress.done(op);
+    await this.between();
   }
 
+  /**
+   * The records of the migration, its schema stays as it is.
+   */
   save () {
-    return State.update(
-      this.pdriver,
-      this.file,
-      this.internals.modSchema,
-      this.internals
+    if (this.internals.dryRun) {
+      return Promise.resolve();
+    }
+
+    return this.pdriver._updateKV(
+      this.internals.migrationState,
+      this.file.name,
+      JSON.stringify(this.internals.modSchema)
     );
   }
 
@@ -342,26 +502,27 @@ class Dml {
         irreversible
           ? { t: 3, a: 'insert', c: [table] }
           : { t: 4, a: 'insert', c: [table, `${this.file.name}#${op}`] },
-      async entry => {
-        if (!rows.length) {
-          return;
-        }
+      entry =>
+        this.tx(async () => {
+          if (!rows.length) {
+            return;
+          }
 
-        if (irreversible) {
-          return this.driver.insert(table, rows);
-        }
+          if (irreversible) {
+            return this.driver.insert(table, rows);
+          }
 
-        const flag = entry.c[1];
-        // rows of an interrupted run of this step
-        await this.driver.runSql(
-          `DELETE FROM ${this.ddl(table)} WHERE ${this.ddl(FLAG)} = ?`,
-          [flag]
-        );
-        await this.driver.insert(
-          table,
-          rows.map(row => Object.assign({}, row, { [FLAG]: flag }))
-        );
-      }
+          const flag = entry.c[1];
+          // rows of an interrupted run of this step
+          await this.driver.runSql(
+            `DELETE FROM ${this.ddl(table)} WHERE ${this.ddl(FLAG)} = ?`,
+            [flag]
+          );
+          await this.driver.insert(
+            table,
+            rows.map(row => Object.assign({}, row, { [FLAG]: flag }))
+          );
+        })
     );
   }
 
@@ -404,28 +565,46 @@ class Dml {
           },
       async entry => {
         if (irreversible || this.internals.dryRun) {
-          return this.driver.runSql(
-            `UPDATE ${this.ddl(table)} SET ${assign} WHERE ${condition.sql}`,
-            values.concat(condition.params)
+          return this.tx(() =>
+            this.driver.runSql(
+              `UPDATE ${this.ddl(table)} SET ${assign} WHERE ${condition.sql}`,
+              values.concat(condition.params)
+            )
           );
         }
 
         await this.backup(entry, table, key.concat(columns), condition);
-        await this.batches(entry, options, rows => {
-          const match = this.byKey(rows, key);
-          return this.driver.runSql(
+        await this.batches(entry, options, match =>
+          this.driver.runSql(
             `UPDATE ${this.ddl(table)} SET ${assign} WHERE ${match.sql}`,
             values.concat(match.params)
-          );
-        });
+          )
+        );
       }
     );
   }
 
   /**
    * delete(table, where, [options]), delete the rows matching where.
+   *
+   * mode 'copy' (default) copies the rows to a backup table first. mode
+   * 'soft' keeps the rows, sets column to the current time, or value, and
+   * marks them in their flag. The application filters them by column, until
+   * purge deletes them.
    */
   delete (table, where, options = {}) {
+    const mode = options.mode || 'copy';
+
+    if (mode === 'soft') {
+      return this.softDelete(table, where, options);
+    }
+
+    if (mode !== 'copy') {
+      throw new Error(
+        `delete("${table}") has no mode "${mode}", use 'copy' or 'soft'`
+      );
+    }
+
     const condition = this.where(where);
     const irreversible = options.irreversible === true;
     const key = irreversible ? null : this.key(table, options, 'delete');
@@ -439,20 +618,117 @@ class Dml {
           : { t: 4, a: 'delete', c: [table, backupName(this.file, op), key] },
       async entry => {
         if (irreversible || this.internals.dryRun) {
+          return this.tx(() =>
+            this.driver.runSql(
+              `DELETE FROM ${this.ddl(table)} WHERE ${condition.sql}`,
+              condition.params
+            )
+          );
+        }
+
+        await this.backup(entry, table, null, condition);
+        await this.batches(entry, options, match =>
+          this.driver.runSql(
+            `DELETE FROM ${this.ddl(table)} WHERE ${match.sql}`,
+            match.params
+          )
+        );
+      }
+    );
+  }
+
+  softDelete (table, where, options) {
+    const column = options.column;
+    const columns = this.columns(table);
+
+    if (typeof column !== 'string') {
+      throw new Error(
+        `delete("${table}") in soft mode needs the column marking the rows ` +
+          "as deleted, { mode: 'soft', column: 'deleted_at' }"
+      );
+    }
+
+    if (!columns || !columns[FLAG]) {
+      throw new Error(
+        `delete("${table}") in soft mode marks the rows in their ${FLAG} ` +
+          'column, which only tables created by v2 migrations have'
+      );
+    }
+
+    const condition = this.where(where);
+    const key = this.key(table, options, 'delete');
+    const time = options.value === undefined;
+
+    return this.step(
+      'delete',
+      [table],
+      op => ({ t: 4, a: 'soft', c: [table, column, key, deleted(this.file, op)] }),
+      entry => {
+        const mark = entry.c[3];
+        const set =
+          `${this.ddl(column)} = ${time ? 'CURRENT_TIMESTAMP' : '?'}, ` +
+          `${this.ddl(FLAG)} = ${this.concat(`COALESCE(${this.ddl(FLAG)}, '')`)}`;
+        const value = time ? [mark] : [toValue(options.value), mark];
+        // rows deleted already, by the application or before, stay as they are
+        const active = {
+          sql: `(${condition.sql}) AND ${this.ddl(column)} IS NULL`,
+          params: condition.params
+        };
+
+        if (this.internals.dryRun) {
+          return this.driver.runSql(
+            `UPDATE ${this.ddl(table)} SET ${set} WHERE ${active.sql}`,
+            value.concat(active.params)
+          );
+        }
+
+        return this.untilDone(table, key, active, options, match =>
+          this.driver.runSql(
+            `UPDATE ${this.ddl(table)} SET ${set} WHERE ${match.sql}`,
+            value.concat(match.params)
+          )
+        );
+      }
+    );
+  }
+
+  /**
+   * purge(table, [migration], [options]), deletes the rows deleted in soft
+   * mode for good, of all migrations or of the one named. It can not be
+   * reverted.
+   */
+  purge (table, migration, options = {}) {
+    if (isObject(migration)) {
+      options = migration;
+      migration = undefined;
+    }
+
+    const key = this.key(table, options, 'purge');
+    const mark = migration ? `|del:${migration}#` : '|del:';
+
+    return this.step(
+      'purge',
+      [table].concat(migration ? [migration] : []),
+      () => ({ t: 3, a: 'purge', c: [table] }),
+      () => {
+        const condition = {
+          sql: `${this.ddl(FLAG)} LIKE ? ESCAPE '!'`,
+          params: [`%${like(mark)}%`]
+        };
+
+        if (this.internals.dryRun) {
           return this.driver.runSql(
             `DELETE FROM ${this.ddl(table)} WHERE ${condition.sql}`,
             condition.params
           );
         }
 
-        await this.backup(entry, table, null, condition);
-        await this.batches(entry, options, rows => {
-          const match = this.byKey(rows, key);
-          return this.driver.runSql(
+        return this.untilDone(table, key, condition, options, match =>
+          this.driver.runSql(
             `DELETE FROM ${this.ddl(table)} WHERE ${match.sql}`,
             match.params
-          );
-        });
+          )
+        );
       }
     );
   }
@@ -486,7 +762,7 @@ class Dml {
         irreversible
           ? { t: 3, a: 'runSql', c: [sql] }
           : { t: 4, a: 'runSql', c: [revert[0], revert[1] || []] },
-      () => this.driver.runSql(sql, params)
+      () => this.tx(() => this.driver.runSql(sql, params))
     );
   }
 
@@ -510,15 +786,18 @@ class Dml {
     const backup = this.ddl(entry.c[1]);
     const select = columns ? columns.map(c => this.ddl(c)).join(', ') : '*';
 
+    // outside of transactions, creating tables commits them in MySQL
     await this.driver.runSql(`DROP TABLE IF EXISTS ${backup}`);
     await this.driver.runSql(
       `CREATE TABLE ${backup} AS SELECT ${select} FROM ${this.ddl(table)} ` +
         'WHERE 1 = 0'
     );
-    await this.driver.runSql(
-      `INSERT INTO ${backup} SELECT ${select} FROM ${this.ddl(table)} ` +
-        `WHERE ${condition.sql}`,
-      condition.params
+    await this.tx(() =>
+      this.driver.runSql(
+        `INSERT INTO ${backup} SELECT ${select} FROM ${this.ddl(table)} ` +
+          `WHERE ${condition.sql}`,
+        condition.params
+      )
     );
 
     entry.b = 1;
@@ -532,13 +811,14 @@ class Dml {
    * interruption sets the same values.
    */
   async batches (entry, options, change) {
-    const size = Number(options.batch) || BATCH;
+    const size = this.batchSize(options);
     const backup = this.ddl(entry.c[1]);
-    const key = entry.c[2].map(k => this.ddl(k)).join(', ');
+    const key = entry.c[2];
+    const order = key.map(k => this.ddl(k)).join(', ');
 
     for (;;) {
       const rows = await this.driver.all(
-        `SELECT ${key} FROM ${backup} ORDER BY ${key} ` +
+        `SELECT ${order} FROM ${backup} ORDER BY ${order} ` +
           `LIMIT ${size} OFFSET ${entry.o}`
       );
 
@@ -546,10 +826,11 @@ class Dml {
         return;
       }
 
-      await change(rows);
+      await this.tx(() => change(this.byKey(rows, key)));
       entry.o += rows.length;
       log.verbose(`[dml] ${this.file.name}: ${entry.o} rows ${entry.a}d`);
       await this.save();
+      await this.between();
     }
   }
 }
@@ -560,12 +841,14 @@ class Dml {
  */
 const reverts = {
   insert: (d, [table, flag]) =>
-    d.driver.runSql(
-      `DELETE FROM ${d.ddl(table)} WHERE ${d.ddl(FLAG)} = ?`,
-      [flag]
+    d.tx(() =>
+      d.driver.runSql(
+        `DELETE FROM ${d.ddl(table)} WHERE ${d.ddl(FLAG)} = ?`,
+        [flag]
+      )
     ),
 
-  runSql: (d, [sql, params]) => d.driver.runSql(sql, params),
+  runSql: (d, [sql, params]) => d.tx(() => d.driver.runSql(sql, params)),
 
   update: async (d, [table, backup, key, columns]) => {
     let offset = 0;
@@ -583,10 +866,12 @@ const reverts = {
         return;
       }
 
-      await Promise.each(rows, row =>
-        d.driver.runSql(
-          `UPDATE ${d.ddl(table)} SET ${assign} WHERE ${match}`,
-          columns.map(c => row[c]).concat(key.map(k => row[k]))
+      await d.tx(() =>
+        Promise.each(rows, row =>
+          d.driver.runSql(
+            `UPDATE ${d.ddl(table)} SET ${assign} WHERE ${match}`,
+            columns.map(c => row[c]).concat(key.map(k => row[k]))
+          )
         )
       );
       offset += rows.length;
@@ -608,12 +893,32 @@ const reverts = {
       .join(' AND ');
 
     // rows deleted by the step only, those not deleted yet stay as they are
-    await d.driver.runSql(
-      `INSERT INTO ${d.ddl(table)} (${columns}) SELECT ${columns} FROM ` +
-        `${d.ddl(backup)} ${d.ddl('__dbm_b')} WHERE NOT EXISTS (SELECT 1 ` +
-        `FROM ${d.ddl(table)} ${d.ddl('__dbm_t')} WHERE ${match})`
+    await d.tx(() =>
+      d.driver.runSql(
+        `INSERT INTO ${d.ddl(table)} (${columns}) SELECT ${columns} FROM ` +
+          `${d.ddl(backup)} ${d.ddl('__dbm_b')} WHERE NOT EXISTS (SELECT 1 ` +
+          `FROM ${d.ddl(table)} ${d.ddl('__dbm_t')} WHERE ${match})`
+      )
     );
-  }
+  },
+
+  soft: (d, [table, column, key, mark]) =>
+    d.untilDone(
+      table,
+      key,
+      {
+        sql: `${d.ddl(FLAG)} LIKE ? ESCAPE '!'`,
+        params: [`%${like(mark)}%`]
+      },
+      {},
+      match =>
+        d.driver.runSql(
+          `UPDATE ${d.ddl(table)} SET ${d.ddl(column)} = NULL, ` +
+            `${d.ddl(FLAG)} = NULLIF(REPLACE(${d.ddl(FLAG)}, ?, ''), '') ` +
+            `WHERE ${match.sql}`,
+          [mark].concat(match.params)
+        )
+    )
 };
 
 const irreversibleSteps = internals =>
@@ -625,8 +930,8 @@ const irreversibleSteps = internals =>
  * Reverts the recorded steps, the last first. Steps with a backup table
  * restore the rows from it and drop it afterwards.
  */
-const revert = async (context, file, internals, pdriver) => {
-  const d = new Dml(context, file, internals, pdriver, null);
+const revert = async (context, file, internals, pdriver, d) => {
+  d = d || new Dml(context, file, internals, pdriver, null);
   const mod = internals.modSchema;
 
   while (mod.s.length) {
@@ -637,10 +942,10 @@ const revert = async (context, file, internals, pdriver) => {
       throw new Error(`Invalid state record of a dml migration, ${entry.a}`);
     }
 
-    if (internals.dryRun && backup) {
+    if (internals.dryRun && (backup || entry.a === 'soft')) {
       log.info(
-        `[dml] would restore the rows of ${entry.a}("${entry.c[0]}") from ` +
-          entry.c[1]
+        `[dml] would revert ${entry.a}("${entry.c[0]}")` +
+          (backup ? ` from ${entry.c[1]}` : '')
       );
     } else {
       // b: 1 the backup is complete, 2 the rows are restored from it
@@ -662,6 +967,21 @@ const revert = async (context, file, internals, pdriver) => {
   await State.deleteState(pdriver, file, internals);
 };
 
+const irreversibleError = (file, internals) => {
+  const irreversible = irreversibleSteps(internals);
+
+  if (!irreversible.length) {
+    return null;
+  }
+
+  const err = new Error(
+    `Migration "${file.name}" can not be reverted, it ran ` +
+      `${irreversible.join(', ')}, which can not be reverted.`
+  );
+  err.irreversible = true;
+  return err;
+};
+
 const opts = context => ({
   options: context.internals.safeOptions,
   dbm: context.internals.safeOptions.dbmigrate
@@ -675,14 +995,8 @@ const down = async (context, driver, file, { abort } = {}) => {
     await State.startMigration(pdriver, file, internals, { op: 'down' });
   }
 
-  const irreversible = irreversibleSteps(internals);
-  if (irreversible.length) {
-    const err = new Error(
-      `Migration "${file.name}" can not be reverted, it ran ` +
-        `${irreversible.join(', ')} with { irreversible: true }.`
-    );
-    err.irreversible = true;
-
+  const err = irreversibleError(file, internals);
+  if (err) {
     if (abort !== true) {
       await State.endMigration(pdriver, file, internals);
     }
@@ -695,15 +1009,16 @@ const down = async (context, driver, file, { abort } = {}) => {
   return Promise.promisify(context.deleteMigrationRecord.bind(context))(file);
 };
 
-const up = async (context, driver, file) => {
-  const internals = context.internals;
-  const pdriver = context._pdriver;
+/**
+ * Runs the migration, after recovering an interrupted run, and rolls it
+ * back if it fails. Shared by the foreground and the background workers.
+ *
+ * hooks.rollingBack: records that the rollback started
+ * hooks.restart: records a fresh start after recovering by rollback
+ */
+const execute = async (context, file, internals, pdriver, interrupted, progress, work, hooks) => {
   let recovery = null;
 
-  const interrupted = await State.startMigration(pdriver, file, internals, {
-    recover: true
-  });
-
   if (interrupted) {
     const mode = recoveryMode(file, interrupted);
     log.warn(
@@ -713,29 +1028,32 @@ const up = async (context, driver, file) => {
     );
 
     if (mode === 'rollback') {
-      await State.rollingBack(pdriver, internals);
+      await hooks.rollingBack();
       await revert(context, file, internals, pdriver);
       internals.modSchema = { i: {}, c: {}, f: {}, s: [] };
-      await State.endMigration(pdriver, file, internals);
-      await State.startMigration(pdriver, file, internals);
+      await hooks.restart();
     } else {
       recovery = interrupted;
     }
   }
 
   internals.migrationDone = recovery ? recovery.done : 0;
-  const db = new Dml(context, file, internals, pdriver, recovery);
+  const db = new Dml(context, file, internals, pdriver, recovery, progress, work);
 
   try {
     await file.get().migrate(db, opts(context));
   } catch (err) {
+    if (err && err.stopped) {
+      throw err;
+    }
+
     describeFailure(err, db, internals);
 
     if (irreversibleSteps(internals).length) {
       log.error(
         `Migration "${file.name}" failed and can not be rolled back, it ` +
-          'ran a step with { irreversible: true }. The steps executed ' +
-          'stay, the next run continues after them.'
+          'ran a step which can not be reverted. The steps executed stay, ' +
+          'the next run continues after them.'
       );
       throw err;
     }
@@ -746,8 +1064,34 @@ const up = async (context, driver, file) => {
         (err && err.message) || err
       }`
     );
-    await State.rollingBack(pdriver, internals);
-    await down(context, driver, file, { abort: true });
+    await hooks.rollingBack();
+    await revert(context, file, internals, pdriver, db);
+    err.rolledBack = true;
+    throw err;
+  }
+};
+
+const up = async (context, driver, file) => {
+  const internals = context.internals;
+  const pdriver = context._pdriver;
+
+  const interrupted = await State.startMigration(pdriver, file, internals, {
+    recover: true
+  });
+
+  try {
+    await execute(context, file, internals, pdriver, interrupted, null, {}, {
+      rollingBack: () => State.rollingBack(pdriver, internals),
+      restart: async () => {
+        await State.endMigration(pdriver, file, internals);
+        await State.startMigration(pdriver, file, internals);
+      }
+    });
+  } catch (err) {
+    if (err && err.rolledBack) {
+      await State.endMigration(pdriver, file, internals);
+    }
+
     throw err;
   }
 
@@ -755,4 +1099,17 @@ const up = async (context, driver, file) => {
   return State.endMigration(pdriver, file, internals);
 };
 
-module.exports = { isDml, checkType, up, down, Dml, FLAG, insertRows };
+module.exports = {
+  isDml,
+  isBackground,
+  checkType,
+  up,
+  down,
+  execute,
+  revert,
+  irreversibleError,
+  Dml,
+  Stopped,
+  FLAG,
+  insertRows
+};