knex-migrator
Advanced tools
A database migration tool for knex.js, which supports MySQL and SQlite3.
npm install knex-migrator --save
or
yarn add knex-migrator
Add me to your globals:
npm install --global knex-migratorup and the down function to ensure a full rollback.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.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', 'mysql2', '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.
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.
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.
| 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 |
You can configure each migration script.
module.exports.config = {
transaction: Boolean
}
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();
}
$ 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]
# Skips a specific migration script
--skip
# Runs only a specific migration script
--only
# Path to MigratorConfig.js
--mgpath
# 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
# Ignores the migration lock
--force
# Version you would like to rollback to
--v
# Ignores the migration lock
--force
DEBUG=knex-migrator:* knex-migrator migrate
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: { ... }
});
# Health
knexMigrator.isDatabaseOK
# Initialise database
knexMigrator.init
# Migrate database
knexMigrator.migrate
# Rollback database
knexMigrator.rollback
# Reset database
knexMigrator.reset
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();
}
});
yarn lint run just eslintyarn test run eslint && then testsNODE_ENV=testing-mysql yarn test to test with MySQLyarn shipCopyright (c) 2013-2022 Ghost Foundation - Released under the MIT license.
FAQs
Database migrations with knex.
The npm package knex-migrator receives a total of 3,206 weekly downloads. As such, knex-migrator popularity was classified as popular.
We found that knex-migrator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 31 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.