knex-migrator 4.0.5

package/lib/index.js

@@ -0,0 +1,1243 @@
+const _ = require('lodash');
+const path = require('path');
+const Promise = require('bluebird');
+const debug = require('debug')('knex-migrator:index');
+const database = require('./database');
+const utils = require('./utils');
+const errors = require('./errors');
+const logging = require('../logging');
+const migrations = require('../migrations');
+const locking = require('./locking');
+
+/**
+ * @description Prototype of Knex-migrator.
+ * @param {Object} options
+ * @constructor
+ */
+function KnexMigrator(options = {}) {
+    let config = utils.loadConfig(options);
+
+    if (!config.database) {
+        throw new Error('MigratorConfig.js needs to export a database config.');
+    }
+
+    if (!config.migrationPath) {
+        throw new Error('MigratorConfig.js needs to export the location of your migration files.');
+    }
+
+    if (!config.currentVersion) {
+        throw new Error('MigratorConfig.js needs to export the a current version.');
+    }
+
+    this.executedFromShell = options.executedFromShell;
+    this.currentVersion = config.currentVersion;
+    this.migrationPath = config.migrationPath;
+    this.subfolder = config.subfolder || 'versions';
+
+    this.dbConfig = config.database;
+}
+
+/**
+ * `knex-migrator init`
+ *
+ * @description This task will run init scripts.
+ *
+ * The `init` command goes through the following steps:
+ *
+ * 1. Create a database knex connection.
+ * 2. Create database if it does not exist.
+ * 3. Create tables for knex-migrator (migrations, migrations-lock)
+ * 4. Run table upgrades/migrations if available.
+ * 5. Lock the tables to avoid running migrations in parallel.
+ * 6. Execute hooks and init scripts.
+ * 7. Init completion: add all existing migration scripts to the database to make it possible to detect a state of the database correctly.
+ * 8. Unlock tables.
+ * 9. Disconnect from database otherwise the CLI won't close properly.
+ *
+ * The `init` command can be triggered via `knex-migrator migrate --init`.
+ * This is a feature which makes it easier to not having to differentiate if a database needs a migration or an
+ * initilisation. The special characteristic of this combo is that the init completation shouldn't run, because
+ * otherwise we would overjump migration files to execute.
+ *
+ * @param {Object} options - Custom options you can pass in (disableHooks, noScripts, skipInitCompletion, only, skip)
+ * @returns {Bluebird<R>}
+ */
+KnexMigrator.prototype.init = function init(options) {
+    options = options || {};
+
+    let self = this,
+        disableHooks = options.disableHooks,
+        noScripts = options.noScripts,
+        skipInitCompletion = options.skipInitCompletion,
+        skippedTasks = [],
+        hooks = {};
+
+    try {
+        if (!disableHooks) {
+            hooks = require(path.join(self.migrationPath, '/hooks/init'));
+        }
+    } catch (err) {
+        debug('Hook Error: ' + err.message);
+        debug('No hooks found, no problem.');
+    }
+
+    this.connection = database.connect(this.dbConfig);
+
+    return database.createDatabaseIfNotExist(self.dbConfig)
+        .then(function () {
+            if (noScripts) {
+                return;
+            }
+
+            // @NOTE: create table outside of the transaction! (implicit)
+            return database.createMigrationsTable(self.connection).then(function () {
+                return migrations.run(self.connection).then(function () {
+                    return locking.lock(self.connection)
+                        .then(function () {
+                            if (hooks.before) {
+                                debug('Before hook');
+                                return hooks.before({
+                                    connection: self.connection
+                                });
+                            }
+                        })
+                        .then(function executeMigrate() {
+                            return self._migrateTo({
+                                version: 'init',
+                                only: options.only,
+                                skip: options.skip
+                            });
+                        })
+                        .then(function (response) {
+                            skippedTasks = response.skippedTasks;
+
+                            if (hooks.after) {
+                                debug('After hook');
+                                return hooks.after({
+                                    connection: self.connection
+                                });
+                            }
+                        })
+                        .then(function () {
+                            const initTasks = utils.listFiles(path.join(self.migrationPath, 'init'));
+
+                            /**
+                             * CASE 1: You can disable init completion manually
+                             * CASE 2: Only skip init completion if you have all init scripts in place already!!
+                             *
+                             * Example:
+                             * - knex-migrator migrate --init should not execute init completion
+                             * -> does not run init completion
+                             *
+                             * Example:
+                             * - knex-migrator init (process was destroyed, you only have 1 init script in your db)
+                             * - knex-migrator init (the other init script get's executed)
+                             * -> run init completion
+                             *
+                             */
+                            if (skippedTasks.length === initTasks.length || skipInitCompletion) {
+                                return Promise.resolve();
+                            }
+
+                            let versionsToMigrateTo;
+
+                            // CASE: insert all migration files, otherwise you will run into problems
+                            // e.g. you are on 1.2, you initialise the database, but there is 1.3 migration script
+                            try {
+                                versionsToMigrateTo = utils.readVersionFolders(
+                                    path.join(self.migrationPath, self.subfolder)) || [];
+                            } catch (err) {
+                                // CASE: versions folder does not exists
+                                if (err.code === 'READ_FOLDERS') {
+                                    return Promise.resolve();
+                                }
+
+                                throw err;
+                            }
+
+                            return database.createTransaction(self.connection, function (transacting) {
+                                // CASE: Run over all migration scripts and add the file name to the database.
+                                return Promise.each(versionsToMigrateTo, function (versionToMigrateTo) {
+                                    let versionPath = path.join(self.migrationPath, self.subfolder, versionToMigrateTo);
+                                    let filesToMigrateTo = utils.listFiles(versionPath) || [];
+
+                                    return Promise.each(filesToMigrateTo, function (fileToMigrateTo) {
+                                        // CASE: check if migration exists, do not insert twice
+                                        return transacting('migrations')
+                                            .where('name', fileToMigrateTo)
+                                            .then(function (migrationExists) {
+                                                if (migrationExists.length) {
+                                                    return Promise.resolve();
+                                                }
+
+                                                return transacting('migrations')
+                                                    .insert({
+                                                        name: fileToMigrateTo,
+                                                        version: versionToMigrateTo,
+                                                        currentVersion: self.currentVersion
+                                                    });
+                                            });
+                                    });
+                                });
+                            });
+                        })
+                        .then(function () {
+                            return locking.unlock(self.connection);
+                        })
+                        .catch(function (err) {
+                            if (err instanceof errors.MigrationsAreLockedError) {
+                                throw err;
+                            }
+
+                            if (err instanceof errors.LockError) {
+                                throw err;
+                            }
+
+                            return locking.unlock(self.connection)
+                                .then(function () {
+                                    throw err;
+                                });
+                        });
+                });
+            });
+        })
+        .then(function onInitSuccess() {
+            debug('Init Success');
+        })
+        .catch(function onInitError(err) {
+            // CASE: Do not rollback if migrations are locked
+            if (err instanceof errors.MigrationsAreLockedError) {
+                throw err;
+            }
+
+            // CASE: Do not rollback migration scripts, if lock error
+            if (err instanceof errors.LockError) {
+                throw err;
+            }
+
+            // CASE: ETIMEDOUT, ENOTFOUND
+            if (err instanceof errors.DatabaseError) {
+                throw err;
+            }
+
+            debug('Rolling back: ' + err.message);
+
+            return self._rollback({
+                version: 'init',
+                skippedTasks: {
+                    init: skippedTasks
+                }
+            }).then(function () {
+                throw err;
+            }).catch(function (innerErr) {
+                if (errors.utils.isIgnitionError(innerErr)) {
+                    throw err;
+                }
+
+                throw new errors.RollbackError({
+                    message: innerErr.message,
+                    err: innerErr,
+                    context: `OuterError: ${err.message}`
+                });
+            });
+        })
+        .finally(function () {
+            let ops = [];
+
+            if (hooks.shutdown) {
+                ops.push(function shutdownHook() {
+                    debug('Shutdown hook');
+                    return hooks.shutdown({
+                        executedFromShell: self.executedFromShell
+                    });
+                });
+            }
+
+            ops.push(function destroyConnection() {
+                debug('Destroy connection');
+                return self.connection.destroy()
+                    .then(function () {
+                        debug('Destroyed connection');
+                    });
+            });
+
+            return Promise.each(ops, function (op) {
+                return op.bind(self)();
+            });
+        });
+};
+
+/**
+ * `knex-migrator migrate`
+ *
+ * @description This task will run migration scripts.
+ *
+ * The `migrate` task runs through the following steps:
+ *
+ * 1. Create a database knex connection.
+ * 2. Ensure connection works as expected.
+ * 3. Run table upgrades/migrations if available.
+ * 4. Lock the target tables to avoid running migrations in parallel.
+ * 5. Perform an integrity check to figure out which migrations need to run (compare files against database)
+ * 6. Execute migrations.
+ * 7. Unlock table.
+ * 8. Disconnect from database otherwise the CLI won't close properly.
+ *
+ * @param {Object} options - Custom options you can pass in (version, force, init, only, skip)
+ * @returns {Bluebird<any>}
+ */
+KnexMigrator.prototype.migrate = function migrate(options) {
+    options = options || {};
+
+    let self = this,
+        onlyVersion = options.version,
+        force = options.force,
+        init = options.init,
+        onlyFile = options.only,
+        versionsToMigrate = [],
+        hooks = {};
+
+    // CASE: you can only use only in combination with the version flag
+    if (onlyFile && !onlyVersion) {
+        onlyFile = null;
+    }
+
+    if (onlyVersion) {
+        debug('onlyVersion: ' + onlyVersion);
+    }
+
+    // CASE: `--init` flag is passed. Combo feature.
+    if (init) {
+        return this.init()
+            .then(function () {
+                return self.migrate(_.omit(options, 'init'));
+            });
+    }
+
+    try {
+        hooks = require(path.join(self.migrationPath, '/hooks/migrate'));
+    } catch (err) {
+        debug('Hook Error: ' + err.message);
+        debug('No hooks found, no problem.');
+    }
+
+    this.connection = database.connect(this.dbConfig);
+
+    return database.ensureConnectionWorks(this.connection)
+        .then(function () {
+            return migrations.run(self.connection);
+        })
+        .then(function () {
+            return locking.lock(self.connection);
+        })
+        .then(function () {
+            return self._integrityCheck({
+                force: force
+            });
+        })
+        .then(function (result) {
+            _.each(result, function (value, version) {
+                // CASE: Log which versions won't be executed based on the "only" flag
+                if (onlyVersion && version !== onlyVersion) {
+                    debug('Do not execute: ' + version);
+                    return;
+                }
+            });
+
+            if (onlyVersion) {
+                // CASE: filter out versions which should not run
+                let containsVersion = _.find(result, function (obj, key) {
+                    return key === onlyVersion;
+                });
+
+                if (!containsVersion) {
+                    logging.warn('Cannot find requested version: ' + onlyVersion);
+                }
+            }
+
+            _.each(result, function (value, version) {
+                // CASE: compare files on disk with files in database
+                if (value.expected !== value.actual) {
+                    debug('Need to execute migrations for: ' + version);
+                    versionsToMigrate.push(version);
+                }
+            });
+        })
+        .then(function executeBeforeHook() {
+            if (!versionsToMigrate.length) {
+                return;
+            }
+
+            if (hooks.before) {
+                debug('Before hook');
+                return hooks.before({
+                    connection: self.connection
+                });
+            }
+        })
+        .then(function executeMigrations() {
+            if (!versionsToMigrate.length) {
+                return;
+            }
+
+            return Promise.each(versionsToMigrate, function (versionToMigrate) {
+                return self._migrateTo({
+                    version: versionToMigrate,
+                    only: onlyFile,
+                    hooks: hooks
+                });
+            });
+        })
+        .then(function executeAfterHook() {
+            if (!versionsToMigrate.length) {
+                return;
+            }
+
+            if (hooks.after) {
+                debug('After hook');
+                return hooks.after({
+                    connection: self.connection
+                });
+            }
+        })
+        .then(function () {
+            return locking.unlock(self.connection);
+        })
+        .catch(function (err) {
+            // CASE: Do not rollback if migrations are locked
+            if (err instanceof errors.MigrationsAreLockedError) {
+                throw err;
+            }
+
+            // CASE: Do not rollback migration scripts, if lock error
+            if (err instanceof errors.LockError) {
+                throw err;
+            }
+
+            // CASE: ETIMEDOUT, ENOTFOUND
+            if (err instanceof errors.DatabaseError) {
+                throw err;
+            }
+
+            if (err.context && err.context.name) {
+                debug(`Task failed: ${err.context.name}`);
+            }
+
+            debug(`Rolling back: ${err.message}`);
+
+            versionsToMigrate.reverse();
+
+            // CASE: rollback in reversed order
+            return Promise.each(versionsToMigrate, function (version) {
+                return self._rollback({version: version, task: err.context});
+            }).then(function () {
+                throw err;
+            }).catch(function (innerErr) {
+                if (errors.utils.isIgnitionError(innerErr)) {
+                    throw err;
+                }
+
+                throw new errors.RollbackError({
+                    message: innerErr.message,
+                    err: innerErr,
+                    context: `OuterError: ${err.message}`
+                });
+            }).finally(function () {
+                return locking.unlock(self.connection);
+            });
+        }).finally(function () {
+            let ops = [];
+
+            if (hooks.shutdown) {
+                ops.push(function shutdownHook() {
+                    debug('Shutdown hook');
+                    return hooks.shutdown({
+                        executedFromShell: self.executedFromShell
+                    });
+                });
+            }
+
+            ops.push(function destroyConnection() {
+                debug('Destroy connection');
+                return self.connection.destroy()
+                    .then(function () {
+                        debug('Destroyed connection');
+                    });
+            });
+
+            return Promise.each(ops, function (op) {
+                return op.bind(self)();
+            });
+        });
+};
+
+/**
+ * `knex-migrator reset`
+ *
+ * @description The rest command will do a full hard reset.
+ *
+ * It will:
+ *
+ * 1. Create a connection to the database.
+ * 2. Ensure connection works as expected.
+ * 3. Lock the table to avoid running reset in parallel.
+ * 4. Run table upgrades/migrations if available.
+ * 5. Drop the database.
+ *
+ * If you pass the "force" flag, you will skip step 2-4.
+ *
+ * @param {Object} options - Custom options the user can pass in (force)
+ * @returns {*}
+ */
+KnexMigrator.prototype.reset = function reset(options) {
+    options = options || {};
+
+    let self = this;
+    let force = options.force;
+
+    this.connection = database.connect(this.dbConfig);
+
+    // CASE: ignore lock completely and drop the db
+    if (force) {
+        return database.drop({
+            connection: self.connection,
+            dbConfig: self.dbConfig
+        }).catch(function onRestError(err) {
+            // Database does not exist. MySql.
+            if (err.errno === 1049) {
+                return Promise.resolve();
+            }
+
+            throw err;
+        }).finally(function () {
+            debug('Destroy connection');
+            return self.connection.destroy()
+                .then(function () {
+                    debug('Destroyed connection');
+                });
+        });
+    }
+
+    return database.ensureConnectionWorks(this.connection)
+        .then(function () {
+            return migrations.run(self.connection);
+        })
+        .then(function () {
+            return locking.lock(self.connection);
+        })
+        .then(function () {
+            return database.drop({
+                connection: self.connection,
+                dbConfig: self.dbConfig
+            });
+        })
+        .catch(function onRestError(err) {
+            if (err instanceof errors.MigrationsAreLockedError) {
+                throw err;
+            }
+
+            // CASE: ETIMEDOUT, ENOTFOUND
+            if (err instanceof errors.DatabaseError) {
+                throw err;
+            }
+
+            debug('Reset error: ' + err.message);
+
+            // CASE: Database does not exist. For MySql.
+            if (err.errno === 1049) {
+                return Promise.resolve();
+            }
+
+            return locking.unlock(self.connection)
+                .then(function () {
+                    throw err;
+                });
+        })
+        .finally(function () {
+            debug('Destroy connection');
+            return self.connection.destroy()
+                .then(function () {
+                    debug('Destroyed connection');
+                });
+        });
+};
+
+/**
+ * `knex-migrator health`
+ *
+ * @description This task detects the (migration) state of your database.
+ *
+ * It asks the database if....
+ *
+ * - the database was initialised?
+ * - migration files need to be executed?
+ *
+ * The task runs through the following steps:
+ *
+ * 1. Create a database connection.
+ * 2. Ensure the connection works (credentials are correct)
+ * 3. Run table upgrades/migrations if available.
+ * 4. Asks if the database is locked and aborts if so.
+ * 5. Perform an integrity check to figure out which migrations need to run (compare files against database)
+ * 6. Returns result.
+ * 7. Destroy connection.
+ *
+ * @returns {Bluebird<any>}
+ */
+KnexMigrator.prototype.isDatabaseOK = function isDatabaseOK() {
+    let self = this;
+    this.connection = database.connect(this.dbConfig);
+
+    return database.ensureConnectionWorks(this.connection)
+        .then(function () {
+            return migrations.run(self.connection);
+        })
+        .then(function () {
+            return locking.isLocked(self.connection);
+        })
+        .then(function () {
+            return self._integrityCheck();
+        })
+        .then(function (result) {
+            // CASE: if an init script was removed, the health check will be positive (see #48)
+            if (result.init && result.init.expected > result.init.actual) {
+                throw new errors.DatabaseIsNotOkError({
+                    message: 'Please run knex-migrator init',
+                    code: 'DB_NOT_INITIALISED'
+                });
+            }
+
+            _.each(_.omit(result, 'init'), function (value) {
+                // CASE: there are more migrations expected than have been run, database needs to be migrated
+                if (value.expected > value.actual) {
+                    throw new errors.DatabaseIsNotOkError({
+                        message: 'Migrations are missing. Please run `knex-migrator migrate`.',
+                        code: 'DB_NEEDS_MIGRATION',
+                        help: `Expected: ${value.expected} items in migrations table, found: ${value.actual}`
+                    });
+                    // CASE: there are more actual migrations than expected, something has gone wrong :(
+                } else if (value.expected < value.actual) {
+                    throw new errors.DatabaseIsNotOkError({
+                        message: 'Detected more items in the migrations table than expected. Please manually inspect the migrations table.',
+                        code: 'MIGRATION_STATE_ERROR',
+                        help: `Expected: ${value.expected} items in migrations table, found: ${value.actual}`
+                    });
+                }
+            });
+        })
+        .catch(function (err) {
+            // CASE: database does not exist
+            if (err.errno === 1049) {
+                throw new errors.DatabaseIsNotOkError({
+                    message: 'Please run knex-migrator init',
+                    code: 'DB_NOT_INITIALISED'
+                });
+            }
+
+            throw err;
+        })
+        .finally(function () {
+            if (!self.connection) {
+                return;
+            }
+
+            debug('Destroy connection');
+            return self.connection.destroy()
+                .then(function () {
+                    debug('Destroyed connection');
+                });
+        });
+};
+
+/**
+ * `knex-migrator rollback`
+ *
+ * @description This task will rollback the database to a version.
+ *
+ * It will:
+ *
+ * 1. Create a connection to the database.
+ * 2. Ensure the connection works (credentials are correct)
+ * 3. Asks the database if the lock is active.
+ * 4. If the lock is not active, you cannot rollback. This is the current default behaviour.
+ * 5. If you pass the "force" flag, you can rollback if the lock is inactive.
+ * 6. Executes rollback helper to rollback to a version.
+ * 7. Destroy connection.
+ *
+ * @param {Object} options - Custom options the user can pass in (force, version, v, disableHooks)
+ * @returns {Bluebird<any>}
+ */
+KnexMigrator.prototype.rollback = function rollback(options) {
+    options = options || {};
+
+    let self = this;
+    let force = options.force;
+    let version = options.version || options.v;
+    let disableHooks = options.disableHooks;
+    let hooks = {};
+
+    this.connection = database.connect(this.dbConfig);
+
+    const helper = function helper() {
+        return new Promise(function (resolve, reject) {
+            try {
+                if (!disableHooks) {
+                    // @TODO: load init or migrate hooks
+                    hooks = require(path.join(self.migrationPath, '/hooks/init'));
+                }
+            } catch (err) {
+                debug('Hook Error: ' + err.message);
+                debug('No hooks found, no problem.');
+            }
+
+            if (hooks.before) {
+                return hooks.before({
+                    connection: self.connection
+                }).then(resolve).catch(reject);
+            }
+
+            resolve();
+        }).then(function () {
+            let whereQuery = {};
+
+            // CASE 1: rollback to specific version (query all and filter out)
+            // CASE 2: rollback current version you are on
+            if (version) {
+                debug(`Rollback to specific version: ${version}`);
+                whereQuery = {};
+            } else {
+                whereQuery = {
+                    currentVersion: self.currentVersion
+                };
+            }
+
+            return self.connection('migrations')
+                .where(whereQuery)
+                .then(function (values) {
+                    if (!values.length) {
+                        throw new errors.IncorrectUsageError({
+                            message: 'No migrations available to rollback.'
+                        });
+                    }
+
+                    // CASE: filter out all versions which are smaller than the version we want to rollback to
+                    if (version) {
+                        values = _.filter(values, function (value) {
+                            return utils.isGreaterThanVersion({
+                                greaterVersion: value.version,
+                                smallerVersion: version
+                            });
+                        });
+                    }
+
+                    // @NOTE: we never ever rollback init scripts for now.
+                    //       this can be very dangerous, because it removes tables
+                    // @EXCEPTION: you run init scripts and they fail
+                    values = _.filter(values, function (value) {
+                        return value.version !== 'init';
+                    });
+
+                    values.reverse();
+                    return Promise.each(values, function (value) {
+                        return self._rollback({
+                            version: value.version,
+                            onlyTasks: [value.name]
+                        });
+                    });
+                });
+        }).then(function () {
+            if (hooks.shutdown) {
+                return hooks.shutdown({
+                    executedFromShell: self.executedFromShell
+                });
+            }
+        });
+    };
+
+    return database.ensureConnectionWorks(this.connection)
+        .then(function () {
+            return migrations.run(self.connection);
+        })
+        .then(function () {
+            return locking.isLocked(self.connection);
+        })
+        .then(function () {
+            // CASE: db is not locked, force
+            if (force) {
+                return helper();
+            }
+
+            throw new errors.IncorrectUsageError({
+                message: 'Rollback did not happen.',
+                help: 'Use --force if you want to force a rollback. By default, rollbacks are only allowed if your database is locked.'
+            });
+        })
+        .catch(function (err) {
+            if (err instanceof errors.MigrationsAreLockedError) {
+                return helper()
+                    .then(function () {
+                        return locking.unlock(self.connection);
+                    });
+            }
+
+            throw err;
+        })
+        .finally(function () {
+            if (!self.connection) {
+                return;
+            }
+
+            debug('Destroy connection');
+            return self.connection.destroy()
+                .then(function () {
+                    debug('Destroyed connection');
+                });
+        });
+};
+
+// @TODO: All of these functions below are helper functions. Source them out as part of https://github.com/TryGhost/knex-migrator/issues/95.
+/**
+ * @description Private helper function for rolling back. It is called in various places to rollback to a state.
+ *
+ * Cases:
+ *
+ * 1. Init or migrate task failed, rollback the previous tasks too.
+ * 2. Rollback task is executed.
+ *
+ * It will:
+ *
+ * 1. Read the migration tasks from disk.
+ * 2. Call "down" fn of target migration script.
+ * 3. Delete migration entry from database.
+ *
+ * @param {Object} options - Custom options the user can pass in (version, skippedTasks, onlyTasks, task)
+ * @returns {Bluebird<IterableOrNever<R>>}
+ * @private
+ */
+KnexMigrator.prototype._rollback = function _rollback(options) {
+    let version = options.version;
+    let skippedTasks = options.skippedTasks || [];
+    let onlyTasks = options.onlyTasks || [];
+    const failedTask = options.task;
+    let tasks = [];
+    let self = this;
+
+    if (version !== 'init') {
+        tasks = utils.readTasks(path.join(this.migrationPath, this.subfolder, version));
+    } else {
+        try {
+            tasks = utils.readTasks(path.join(this.migrationPath, version));
+        } catch (err) {
+            if (err.code === 'MIGRATION_PATH') {
+                tasks = [];
+            } else {
+                throw err;
+            }
+        }
+    }
+
+    // CASE: rollback failed in one of the tasks in init or migrate
+    // CASE: if no task available, you are about to rollback manually `knex-migrator rollback`
+    if (failedTask) {
+        const newTasks = [];
+
+        for (let i = 0; i < tasks.length; i = i + 1) {
+            const task = tasks[i];
+
+            if (task.name !== failedTask.name) {
+                newTasks.push(task);
+            } else if (task.name === failedTask.name) {
+                /**
+                 * @NOTE
+                 *
+                 * The task, which has failed, is never written to the database.
+                 * But we have to double check if the target task was running in a transaction.
+                 *
+                 * Transaction: no need to rollback this task
+                 * No Transaction: we have to rollback this task, because of implicit commits
+                 */
+                if (!failedTask.config || !failedTask.config.transaction) {
+                    newTasks.push(task);
+                }
+
+                break;
+            }
+        }
+
+        tasks = newTasks;
+    }
+
+    // CASE: one of the migrations that are about to be rolled back is marked as irreversible. Exit early without performing any actions
+    const irreversibleMigrations = _.filter(tasks, function (task) {
+        return !!_.get(task, 'config.irreversible');
+    });
+    if (irreversibleMigrations.length) {
+        return Promise.reject(new errors.IrreversibleMigrationError({
+            message: 'Unable to rollback',
+            help: 'There are irreversible migrations when rolling back to the selected version, this typically means data required for earlier versions has been deleted. Please restore from a backup instead.',
+            code: 'IRREVERSIBLE_MIGRATION'
+        }));
+    }
+
+    tasks.reverse();
+
+    return Promise.each(tasks, function (task) {
+        if (skippedTasks[version] && skippedTasks[version].indexOf(task.name) !== -1) {
+            return Promise.resolve();
+        }
+
+        if (onlyTasks.length && onlyTasks.indexOf(task.name) === -1) {
+            return Promise.resolve();
+        }
+
+        if (!task.down) {
+            debug('No down function provided', task.name);
+            return self.connection('migrations')
+                .where({
+                    name: task.name,
+                    version: version,
+                    currentVersion: self.currentVersion
+                })
+                .delete();
+        }
+
+        debug('Rollback', task.name);
+
+        if (task.config && task.config.transaction) {
+            return database.createTransaction(self.connection, function (txn) {
+                return task.down({
+                    transacting: txn
+                });
+            }).then(function () {
+                return self.connection('migrations')
+                    .where({
+                        name: task.name,
+                        version: version
+                    })
+                    .delete();
+            });
+        }
+
+        return task.down({
+            connection: self.connection
+        }).then(function () {
+            return self.connection('migrations')
+                .where({
+                    name: task.name,
+                    version: version
+                })
+                .delete();
+        });
+    });
+};
+
+/**
+ * @description Private migrate helper.
+ *
+ * Cases:
+ * 1. Init task will use this helper to migrate to "init".
+ * 2. Migrate task will use this helper to migrate to a version e.g. "1.1"
+ *
+ * It will:
+ * 1. Read the migration tasks from disk.
+ * 2. Execute hooks.
+ * 3. Create a transaction for the target migration file if configured. Each migration scripts can run in one transaction.
+ *    If multiple versions/scripts are executed, we cannot run all of them in a single txn, because implicit commands can happen in between.
+ * 4. Execute "up" function of migration file.
+ * 5. Returns any skipped task. Skipped tasks are tasks which failed. Only one task is returned, the last one which failed.
+ *
+ * @param {Object} options - Custom options the user can pass in (version, hooks, only, skip)
+ * @returns {Bluebird<{skippedTasks: Array}>}
+ * @private
+ */
+KnexMigrator.prototype._migrateTo = function _migrateTo(options) {
+    options = options || {};
+
+    let self = this,
+        version = options.version,
+        hooks = options.hooks || {},
+        only = options.only || null,
+        skip = options.skip || null,
+        subfolder = this.subfolder,
+        skippedTasks = [],
+        tasks = [];
+
+    if (version !== 'init') {
+        tasks = utils.readTasks(path.join(self.migrationPath, subfolder, version));
+    } else {
+        try {
+            tasks = utils.readTasks(path.join(self.migrationPath, version));
+        } catch (err) {
+            if (err.code === 'MIGRATION_PATH') {
+                tasks = [];
+            } else {
+                throw err;
+            }
+        }
+    }
+
+    if (only !== null) {
+        debug('only: ' + only);
+        tasks = [tasks[only - 1]];
+    } else if (skip !== null) {
+        debug('skip: ' + skip);
+        tasks.splice(skip - 1, 1);
+    }
+
+    debug('Migrate: ' + version + ' with ' + tasks.length + ' tasks.');
+    debug('Tasks: ' + JSON.stringify(tasks));
+
+    return Promise.each(tasks, function executeTask(task) {
+        return self._beforeEach({
+            task: task.name,
+            version: version
+        }).then(function () {
+            if (hooks.beforeEach) {
+                return hooks.beforeEach({
+                    connection: self.connection
+                });
+            }
+        }).then(function () {
+            debug('Running up: ' + task.name);
+
+            if (task.config && task.config.transaction) {
+                return database.createTransaction(self.connection, function (txn) {
+                    return task.up({
+                        transacting: txn
+                    });
+                });
+            }
+
+            return task.up({
+                connection: self.connection
+            });
+        }).then(function () {
+            if (hooks.afterEach) {
+                return hooks.afterEach({
+                    connection: self.connection
+                });
+            }
+        }).then(function () {
+            return self._afterEach({
+                task: task,
+                version: version
+            });
+        }).catch(function (err) {
+            if (err instanceof errors.MigrationExistsError) {
+                debug('Skipping:' + task.name);
+                skippedTasks.push(task.name);
+                return Promise.resolve();
+            }
+
+            /**
+             * @NOTE: When your database encoding is set to utf8mb4 and you set a field length > 191 characters,
+             * MySQL will throw an error, BUT it won't roll back the changes, because ALTER/CREATE table commands are
+             * implicit commands.
+             *
+             * https://bugs.mysql.com/bug.php?id=28727
+             * https://github.com/TryGhost/knex-migrator/issues/51
+             */
+            if (err.code === 'ER_TOO_LONG_KEY') {
+                let match = err.message.match(/`\w+`/g);
+                let table = match[0];
+                let field = match[2];
+
+                throw new errors.MigrationScriptError({
+                    message: 'Field length of %field% in %table% is too long!'.replace('%field%', field).replace('%table%', table),
+                    context: 'This usually happens if your database encoding is utf8mb4.\n' +
+                        'All unique fields and indexes must be lower than 191 characters.\n' +
+                        'Please correct your field length and reset your database with knex-migrator reset.\n',
+                    help: 'Read more here: https://github.com/TryGhost/knex-migrator/issues/51\n',
+                    err: err
+                });
+            }
+
+            throw new errors.MigrationScriptError({
+                message: err.message,
+                help: 'Error occurred while executing the following migration: ' + task.name,
+                context: task,
+                err: err
+            });
+        });
+    }).then(function () {
+        return {
+            skippedTasks: skippedTasks
+        };
+    });
+};
+
+/**
+ * @description Private helper to execute logic before each migration script is executed.
+ *
+ * It ensures that migration scripts are not executed twice.
+ *
+ * @param {Object} options
+ * @returns {*}
+ * @private
+ */
+KnexMigrator.prototype._beforeEach = function _beforeEach(options) {
+    options = options || {};
+
+    let task = options.task,
+        version = options.version;
+
+    return this.connection('migrations')
+        .then(function (migrations) {
+            if (!migrations.length) {
+                return;
+            }
+
+            if (_.find(migrations, {name: task, version: version})) {
+                throw new errors.MigrationExistsError();
+            }
+        });
+};
+
+/**
+ * @description Private helper to execute logic after each migration script is executed.
+ *
+ * It ensures that migration files are inserted into the database.
+ *
+ * @param {Object} options
+ * @returns {*}
+ * @private
+ */
+KnexMigrator.prototype._afterEach = function _afterEach(options) {
+    options = options || {};
+
+    let self = this;
+    let task = options.task;
+    let version = options.version;
+
+    return this.connection('migrations')
+        .insert({
+            name: task.name,
+            version: version,
+            currentVersion: self.currentVersion
+        });
+};
+
+/**
+ * @description Private helper to execute an integrity check. The integrity check compares files against entries in the
+ * database. It returns expected and actual database state.
+ *
+ * @param {Object} options - Custom user options (force)
+ * @returns {Bluebird<any>}
+ * @private
+ */
+KnexMigrator.prototype._integrityCheck = function _integrityCheck(options) {
+    options = options || {};
+
+    let self = this,
+        subfolder = this.subfolder,
+        force = options.force,
+        folders = [],
+        toReturn = {},
+        futureVersions = [];
+
+    // CASE: we always fetch the init scripts and check them
+    // 1. to be able to add more init scripts
+    // 2. to check if migration scripts need's to be executed or not, see https://github.com/TryGhost/knex-migrator/issues/39
+    folders.push('init');
+
+    // CASE: no subfolder yet. You can tell knex-migrator if scripts live on a sub folder.
+    try {
+        folders = folders.concat(utils.readVersionFolders(path.join(self.migrationPath, subfolder)));
+    } catch (err) {
+        // ignore
+    }
+
+    return this
+        .connection('migrations')
+        .select('version')
+        .count('version', {as: 'c'})
+        .groupBy('version')
+        .then((dbMigrations) => {
+            _.each(folders, function (folder) {
+                // CASE: versions/1.1-members or versions/2.0-payments
+                if (folder !== 'init') {
+                    try {
+                        folder = folder.match(/([\d._]+)/)[0];
+                    } catch (err) {
+                        logging.warn('Cannot parse folder name.');
+                        logging.warn('Ignore Folder: ' + folder);
+                        return;
+                    }
+                }
+
+                // CASE:
+                // if your current version is 1.0 and you add migration scripts for the next version 1.1
+                // we won't execute them until your current version changes to 1.1 or until you force KM to migrate to it
+                if (self.currentVersion && !force) {
+                    if (utils.isGreaterThanVersion({smallerVersion: self.currentVersion, greaterVersion: folder})) {
+                        futureVersions.push(folder);
+                    }
+                }
+
+                let actual = 0;
+                let expected;
+
+                const migrationCount = dbMigrations.find(m => m.version === folder);
+                if (migrationCount) {
+                    actual = migrationCount.c;
+                }
+
+                if (folder !== 'init') {
+                    expected = utils.listFiles(path.join(self.migrationPath, subfolder, folder)).length;
+                } else {
+                    expected = utils.listFiles(path.join(self.migrationPath, folder)).length;
+                }
+
+                debug('Version ' + folder + ' expected: ' + expected);
+                debug('Version ' + folder + ' actual: ' + actual);
+
+                toReturn[folder] = {
+                    expected: expected,
+                    actual: actual
+                };
+            });
+
+            // CASE: ensure that either you have to run `migrate --force` or they ran already
+            if (futureVersions.length) {
+                _.each(futureVersions, function (futureVersion) {
+                    if (toReturn[futureVersion].actual !== toReturn[futureVersion].expected) {
+                        logging.warn('knex-migrator is skipping ' + futureVersion);
+                        logging.warn('Current version in MigratorConfig.js is smaller then requested version, use --force to proceed!');
+                        logging.warn('Please run `knex-migrator migrate --v ' + futureVersion + ' --force` to proceed!');
+                        delete toReturn[futureVersion];
+                    }
+                });
+            }
+
+            return toReturn;
+        }).catch(function onMigrationsLookupError(err) {
+            // CASE: no database selected (database.connection.database="")
+            if (err.errno === 1046) {
+                throw new errors.DatabaseIsNotOkError({
+                    message: 'Please define a target database in your configuration.',
+                    help: 'database: {\n\tconnection:\n\t\tdatabase:"database_name"\n\t}\n}\n',
+                    code: 'DB_NOT_INITIALISED'
+                });
+            }
+
+            // CASE: database does not exist
+            if (err.errno === 1049) {
+                throw new errors.DatabaseIsNotOkError({
+                    message: 'Please run knex-migrator init',
+                    code: 'DB_NOT_INITIALISED'
+                });
+            }
+
+            // CASE: migration table does not exist
+            if (err.errno === 1 || err.errno === 1146) {
+                throw new errors.DatabaseIsNotOkError({
+                    message: 'Please run knex-migrator init',
+                    code: 'MIGRATION_TABLE_IS_MISSING'
+                });
+            }
+
+            throw err;
+        });
+};
+
+module.exports = KnexMigrator;