knex-migrator 4.0.5

package/CHANGELOG.md

@@ -0,0 +1,171 @@
+# knex-migrator Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+<a name="3.2.6"></a>
+# [3.2.6](https://github.com/TryGhost/Ghost-CLI/compare/3.2.5...v3.2.6) (2019-03-20)
+
+### Bug fixes
+
+- 🐛 Fixed `knex-migrator migrate --init` 
+
+<a name="3.2.1"></a>
+# [3.2.1](https://github.com/TryGhost/Ghost-CLI/compare/3.2.0...v3.2.1) (2019-03-20)
+
+### Bug fixes
+
+- 🐛 Fixed option collision with commander (`--version` vs `--v`) 
+
+<a name="3.2.0"></a>
+# [3.2.0](https://github.com/TryGhost/Ghost-CLI/compare/3.1.8...v3.2.0) (2019-03-20)
+
+### Features
+
+✨ Added ability to rollback to a specific version 
+
+
+<a name="3.1.6"></a>
+# [3.1.6](https://github.com/TryGhost/Ghost-CLI/compare/3.1.5...v3.1.6) (2018-04-30)
+
+### Node
+* 🔥Drop Node v4 support
+
+### Bug fixes
+
+* 🐛Fixed incorrect version number comparison
+* 🐛Fixed wrong folders order on db initialisation 
+* 🐛Fixed comparing expected and actual migration tasks 
+
+<a name="3.1.3"></a>
+# [3.1.3](https://github.com/TryGhost/Ghost-CLI/compare/3.1.2...v3.1.3) (2018-01-02)
+
+### Improvements
+
+* Optimised error message for lock
+* Added support for specifying the config via options
+
+<a name="3.1.2"></a>
+# [3.1.2](https://github.com/TryGhost/Ghost-CLI/compare/3.1.1...v3.1.2) (2017-12-05)
+
+### Improvements
+
+* Make database upgrades more relaxed
+
+<a name="3.1.1"></a>
+# [3.1.1](https://github.com/TryGhost/Ghost-CLI/compare/3.1.0...v3.1.1) (2017-12-05)
+
+### Improvements
+
+* Added protection against database migrations
+
+<a name="3.1.0"></a>
+# [3.1.0](https://github.com/TryGhost/Ghost-CLI/compare/3.0.10...v3.1.0) (2017-12-05)
+
+### Improvements
+
+* Added more database upgrades
+* Added unique constaint to the migrations table
+* Define field lengths for migrations table
+
+<a name="3.0.10"></a>
+# [3.0.10](https://github.com/TryGhost/Ghost-CLI/compare/3.0.9...v3.0.10) (2017-12-04)
+
+### Fixes
+
+* Fixed `acquired_at` and `released_at` with correct date format
+
+<a name="3.0.9"></a>
+# [3.0.9](https://github.com/TryGhost/Ghost-CLI/compare/3.0.8...v3.0.9) (2017-12-04)
+
+### Fixes
+
+* Do not unlock if lock was never acquired
+
+<a name="3.0.8"></a>
+# [3.0.8](https://github.com/TryGhost/Ghost-CLI/compare/3.0.7...v3.0.8) (2017-12-04)
+
+### Fixes
+
+* Added more npm keywords
+* Rollback should not happen if lock was never acquired
+
+<a name="3.0.7"></a>
+# [3.0.7](https://github.com/TryGhost/Ghost-CLI/compare/3.0.6...v3.0.7) (2017-11-15)
+
+### Fixes
+
+* Added missing `--force` flag for `knex-migrator reset`
+
+<a name="3.0.6"></a>
+# [3.0.6](https://github.com/TryGhost/Ghost-CLI/compare/3.0.5...v3.0.6) (2017-11-04)
+
+### Fixes
+
+* Do not throw error on reset, otherwise it's harder to handle this via the JS API
+* There is no good reason to throw an error, so revert to success response
+
+<a name="3.0.5"></a>
+# [3.0.5](https://github.com/TryGhost/Ghost-CLI/compare/3.0.4...v3.0.5) (2017-11-04)
+
+### Fixes
+
+* Fixed order of rollback
+
+<a name="3.0.4"></a>
+# [3.0.4](https://github.com/TryGhost/Ghost-CLI/compare/3.0.3...v3.0.4) (2017-11-04)
+
+### Fixes
+
+* Fixed rollback for init scripts
+
+<a name="3.0.3"></a>
+# [3.0.3](https://github.com/TryGhost/Ghost-CLI/compare/3.0.2...v3.0.3) (2017-11-04)
+
+### Fixes
+
+* Fixed `--force` flag for `knex-migrator rollback`
+
+<a name="3.0.2"></a>
+# [3.0.2](https://github.com/TryGhost/Ghost-CLI/compare/3.0.1...v3.0.2) (2017-11-03)
+
+### Fixes
+
+* Fixed missing throw/catch behaviour,
+
+<a name="3.0.1"></a>
+# [3.0.1](https://github.com/TryGhost/Ghost-CLI/compare/3.0.0...v3.0.1) (2017-11-03)
+
+### Fixes
+
+* Fixed binary for `knex-migrator rollback`
+
+<a name="3.0.0"></a>
+# [3.0.0](https://github.com/TryGhost/Ghost-CLI/compare/2.1.9...v3.0.0) (2017-11-03)
+
+
+### Breaking Changes
+* You have to export `up` and `down` in your migration scripts. `down` is optional, but highly recommended, otherwise on failure your changes won't rollback completely.
+* The `options` object which is passed into the migration script contains now by default a connection object. (`options.connection`). You have to explicit enable transactions, see README.
+* A new migrations lock table get's added as soon as you run **any** command. You don't have to worry about that.
+* Expect bug fixes in the upcoming days.
+
+### Features
+
+* Support full rollback (auto rollback on error)
+* Shutdown hook
+* Concurrency and locking
+* A new shiny `rollback` command for manual rollback if needed.
+
+<a name="2.1.9"></a>
+# [2.1.9](https://github.com/TryGhost/Ghost-CLI/compare/2.1.8...v2.1.9) (2017-10-26)
+
+### Features
+
+* Enabled Node 8 Support
+
+<a name="2.1.8"></a>
+# [2.1.9](https://github.com/TryGhost/Ghost-CLI/compare/2.1.7...v2.1.8) (2017-10-24)
+
+### Fixes
+
+* Fixed migration order on db initialisation

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013-2021 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,347 @@
+# knex-migrator
+
+A database migration tool for [knex.js](https://github.com/tgriesser/knex), which supports MySQL and SQlite3.
+
+## Features
+
+- [x] JS API
+- [x] CLI Tool
+- [x] Differentiation between database initialization and migration (Support for a database schema, [like we use in Ghost](https://github.com/TryGhost/Ghost/blob/1.16.2/core/server/data/schema/schema.js))
+- [x] Support for database creation
+- [x] Hooks
+- [x] Rollback to latest version
+- [x] Auto-Rollback on error
+- [x] Database health check
+- [x] Supports transactions
+- [x] Full atomic, support for separate DML/DDL scripts (no autocommit)
+- [x] Migration lock
+- [x] Full debug & pretty log support
+- [x] Custom migration folder structure
+- [x] Stable (Used in [Ghost](https://github.com/TryGhost/Ghost) for many years in thousands of blogs in production mode)
+
+# Install
+
+`npm install knex-migrator --save`
+
+or
+
+`yarn add knex-migrator`
+
+Add me to your globals:
+   - `npm install --global knex-migrator`
+
+# Usage
+
+## Pre-word
+
+- Replicas are unsupported, because Knex.js [doesn't support them](https://github.com/tgriesser/knex/issues/2253).
+- Sqlite does **not** support read locks by default. Read [here](https://github.com/TryGhost/knex-migrator/issues/87) why.
+- [Comparison](https://github.com/TryGhost/knex-migrator/issues/119) with other available migration tools.
+- Don't mix DDL/DML statements in a migration script. In MySQL DDL statements use implicit commits.
+- It's highly recommended to write both the `up` and the `down` function to ensure a full rollback.
+- If your process dies while migrations are running, knex-migrator won't be able to release the migration lock.
+  To release to lock you can run `knex-migrator rollback`. **But** it's recommended to check your database first to see in which state it is.
+  You can check the tables `migrations` and `migrations_lock`. The rollback will rollback any migrations which were executed based on your current version.
+
+## Configure knex-migrator
+
+The tool requires a config file in your project root.
+Please add a file named `MigratorConfig.js`. Knex-migrator will load the config file.
+
+
+```
+module.exports = {
+    database: {
+        client:         String          (Required) ['mysql', 'sqlite3']
+        connection: {
+            host:       String,         (Required) [e.g. '127.0.0.1']
+            user:       String,         (Required)
+            password:   String,         (Required)
+            charset:    String,         (Optional) [Default: 'utf8mb4']
+            database:   String          (Required)
+        }
+    },
+    migrationPath:      String,         (Required) [e.g. '/var/www/project/migrations']
+    currentVersion:     String,         (Required) [e.g. '2.0']
+    subfolder:          String          (Optional) [Default: 'versions']
+}
+```
+
+Please take a look at [this real example](https://github.com/TryGhost/Ghost/blob/2.19.3/MigratorConfig.js).
+
+## Folder Structure
+
+```
+project/
+    migrations/
+        hooks/
+            init/
+                index.js
+                before.js
+                shutdown.js
+            migrate/
+                index.js
+                after.js
+                shutdown.js
+        init/
+            1-add-tables.js
+        versions/
+            1.0/
+                1-add-events-table.js
+                2-normalise-settings.js
+            2.0/
+                1-add-timestamps-columns.js
+            2.1/
+                1-remove-empty-strings.js
+                2-add-webhooks-table.js
+                3-add-permissions.js
+```
+
+Please take a look at [this real example](https://github.com/TryGhost/Ghost/tree/2.19.3/core/server/data/migrations).
+
+## Hooks
+
+Knex-migrator offers a couple of hooks, which makes it possible to hook into the migration process. You can create a hook per type: 'init' or 'migrate'. The folder name must be `hooks` and is not configurable. Please create an index.js file to export your functions, see [example](https://github.com/TryGhost/Ghost/blob/2.19.3/core/server/data/migrations/hooks/init/index.js).
+
+|hook|description|
+|---|---|
+|before|is called before anything happens|
+|beforeEach| is called before each migration script|
+|after|is called after everything happened|
+|afterEach|is called after each migration script|
+|shutdown|is called before the migrator shuts down|
+
+
+## Migration Files
+
+### Config
+You can configure each migration script.
+
+```
+module.exports.config = {
+  transaction: Boolean
+}
+```
+
+
+### Examples
+```
+const Promise = require('bluebird');
+
+module.exports.up = function(options) {
+  const connection = options.connection;
+
+  ...
+
+  return Promise.resolve();
+};
+
+module.exports.down = function(options) {
+  const connection = options.connection;
+
+  ...
+
+  return Promise.resolve();
+}
+```
+
+```
+const Promise = require('bluebird');
+
+module.exports.config = {
+  transaction: true
+};
+
+module.exports.up = function(options) {
+  const connection = options.transacting;
+
+  ...
+
+  return Promise.resolve();
+};
+
+module.exports.down = function(options) {
+  const connection = options.transacting;
+
+  ...
+
+  return Promise.resolve();
+}
+```
+
+## CLI
+
+### Commands
+
+#### knex-migrator help
+
+```
+$ knex-migrator help
+Usage: knex-migrator [options] [command]
+
+Options:
+  -v, --version       output the version number
+  -h, --help          output usage information
+
+Commands:
+  init|i [config]     init db
+  migrate|m [config]  migrate db
+  reset|r             reset db
+  health|h            health of db
+  rollback|ro         rollbacks your db
+  help [cmd]          display help for [cmd]
+```
+
+#### knex-migrator health
+
+- Returns the database health/state
+- Based on your current version and your migration scripts
+
+#### knex-migrator init
+
+- Initializes your database based on your init scripts
+- Creates the database if it was not created yet
+
+##### Options
+
+```bash
+# Skips a specific migration script
+--skip
+
+# Runs only a specific migration script
+--only
+
+# Path to MigratorConfig.js
+--mgpath
+```
+
+#### knex-migrator migrate
+
+- Migrates your database to latest version
+- Automatic rollback if an error occurs
+
+##### Options
+
+```bash
+# The version you would like to migrate to
+--v
+
+# Combo Feature to check whether the database was already initialized
+--init
+
+# Force the execution no matter which current version you are on
+--force
+
+# Path to MigratorConfig.js
+--mgpath
+```
+
+#### knex-migrator rollback
+
+- Rolls back your database
+- By default, you can only rollback if the database is locked
+
+##### Options
+
+```bash
+# Ignores the migration lock
+--force
+
+# Version you would like to rollback to
+--v
+```
+
+#### knex-migrator reset
+
+- Resets your database
+- Removes the database
+
+##### Options
+
+```bash
+# Ignores the migration lock
+--force
+```
+
+### Advanced
+
+`DEBUG=knex-migrator:* knex-migrator migrate`
+
+
+## JS API
+
+### Instantiation
+
+```js
+const KnexMigrator = require('knex-migrator');
+
+# Option 1: Pass path to MigratorConfig.js
+const knexMigrator = new KnexMigrator({
+    knexMigratorFilePath: process.cwd()
+});
+
+# Option 2: Pass object with config
+const knexMigrator = new KnexMigrator({
+    knexMigratorConfig: { ... }
+});
+
+```
+
+### Commands
+
+```js
+# Health
+knexMigrator.isDatabaseOK
+
+# Initialise database
+knexMigrator.init
+
+# Migrate database
+knexMigrator.migrate
+
+# Rollback database
+knexMigrator.rollback
+
+# Reset database
+knexMigrator.reset
+```
+
+### Examples
+
+```js
+knexMigrator.isDatabaseOK()
+  .then(function() {
+     // database is OK
+     // initialization & migrations are not missing
+  })
+  .catch(function(err) {
+      if (err.code === 'DB_NOT_INITIALISED') {
+          return knexMigrator.init();
+      }
+
+      if (err.code === 'DB_NEEDS_MIGRATION') {
+        return knexMigrator.migrate();
+      }
+  });
+
+```
+
+# Test
+
+- `yarn lint` run just eslint
+- `yarn test` run eslint && then tests
+- `NODE_ENV=testing-mysql yarn test` to test with MySQL
+
+# Publish
+
+- `yarn ship`
+
+# Copyright & License
+
+Copyright (c) 2013-2021 Ghost Foundation - Released under the [MIT license](LICENSE).
+
+
+
+
+
+

package/bin/knex-migrator

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+var program = require('commander'),
+    pkg = require('../package.json');
+
+program
+    .version(pkg.version, '-v, --version')
+    .command('init [config]', 'init db').alias('i')
+    .command('migrate [config]', 'migrate db').alias('m')
+    .command('reset', 'reset db').alias('r')
+    .command('health', 'health of db').alias('h')
+    .command('rollback', 'rollbacks your db').alias('ro')
+    .parse(process.argv);

package/bin/knex-migrator-health

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+var utils = require('../lib/utils');
+
+var logging = require('../logging');
+var knexMigrator;
+
+utils.getKnexMigrator({path: process.cwd()})
+    .then(function (KnexMigrator) {
+        program
+            .option('--mgpath <path>')
+            .parse(process.argv);
+
+        try {
+            knexMigrator = new KnexMigrator({knexMigratorFilePath: program.mgpath, executedFromShell: true});
+        } catch (err) {
+            logging.error(err);
+            process.exit(1);
+        }
+
+        return knexMigrator.isDatabaseOK()
+            .then(function () {
+                logging.info('Woohoo, Database is healthy');
+            });
+    })
+    .catch(function (err) {
+        logging.error(err.message);
+
+        if (err.help) {
+            logging.info(err.help);
+        }
+
+        process.exit(1);
+    });

package/bin/knex-migrator-init

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+var utils = require('../lib/utils');
+
+var logging = require('../logging');
+var knexMigrator;
+
+utils.getKnexMigrator({path: process.cwd()})
+    .then(function (KnexMigrator) {
+        program
+            .option('--skip <item>')
+            .option('--only <item>')
+            .option('--mgpath <path>')
+            .parse(process.argv);
+
+        try {
+            knexMigrator = new KnexMigrator({knexMigratorFilePath: program.mgpath, executedFromShell: true});
+        } catch (err) {
+            logging.error(err);
+            process.exit(1);
+        }
+
+        return knexMigrator.init({
+            skip: program.skip,
+            only: program.only
+        }).then(function () {
+            logging.info('Finished database init!');
+        });
+    })
+    .catch(function (err) {
+        logging.error(err);
+        process.exit(1);
+    });

package/bin/knex-migrator-migrate

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+var utils = require('../lib/utils');
+
+var logging = require('../logging');
+var knexMigrator;
+
+utils.getKnexMigrator({path: process.cwd()})
+    .then(function (KnexMigrator) {
+        program
+            .option('--v <item>')
+            .option('--only <item>')
+            .option('--mgpath <path>')
+            .option('--force')
+            .option('--init')
+            .parse(process.argv);
+
+        try {
+            knexMigrator = new KnexMigrator({knexMigratorFilePath: program.mgpath, executedFromShell: true});
+        } catch (err) {
+            logging.error(err);
+            process.exit(1);
+        }
+
+        return knexMigrator.migrate({
+            version: program.v,
+            only: program.only,
+            force: program.force,
+            init: program.init
+        }).then(function () {
+            logging.info('Finished database migration!');
+        });
+    })
+    .catch(function (err) {
+        logging.error(err);
+        process.exit(1);
+    });

package/bin/knex-migrator-reset

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+var utils = require('../lib/utils');
+
+var logging = require('../logging');
+var knexMigrator;
+
+utils.getKnexMigrator({path: process.cwd()})
+    .then(function (KnexMigrator) {
+        program
+            .option('--mgpath <path>')
+            .option('--force')
+            .parse(process.argv);
+
+        try {
+            knexMigrator = new KnexMigrator({knexMigratorFilePath: program.mgpath, executedFromShell: true});
+        } catch (err) {
+            logging.error(err);
+            process.exit(1);
+        }
+
+        return knexMigrator.reset({force: program.force})
+            .then(function () {
+                logging.info('Finished database reset!');
+            });
+    })
+    .catch(function (err) {
+        logging.error(err);
+        process.exit(1);
+    });