knex-migrator

library5.3.2jsnpmunverified

knex-migrator is a robust database migration tool built on top of knex.js, specifically designed to handle complex schema changes and initializations. Currently at version 5.3.2, it is known for its stability and is actively used in production by platforms like Ghost CMS. Key features include distinct differentiation between database initialization and subsequent migrations, support for a structured database schema, comprehensive rollback capabilities with auto-rollback on error, transactional migrations, and a migration lock mechanism to prevent concurrent execution. It supports MySQL and SQLite3. The tool emphasizes a strict separation of DDL (Data Definition Language) and DML (Data Manipulation Language) statements within migration scripts to ensure atomic operations and prevent implicit commits, which is a critical differentiator for maintaining data integrity during schema evolution.

database

npm install knex-migrator

package ↗

INSTALL

IMPORT

SIG · KNEX-MIGRATOR

knex-migrator

databasejavascriptv5.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KnexMigrator

✓ import KnexMigrator from 'knex-migrator'; // Or for CommonJS: const KnexMigrator = require('knex-migrator');

✗ import { KnexMigrator } from 'knex-migrator';

The primary programmatic interface is typically the default export (a class) to instantiate the migrator. Named imports for the main class are incorrect.

CLI Usage

✓ npx knex-migrator init npx knex-migrator migrate npx knex-migrator rollback

Most common usage is via the globally installed `knex-migrator` CLI or `npx` for project-local execution. This doesn't involve a direct JS `import`.

MigratorConfig.js

✓ module.exports = { /* ... config object ... */ };

✗ export default { /* ... config object ... */ };

The configuration file `MigratorConfig.js` is typically a CommonJS module export, though ESM could be supported depending on Node.js environment and explicit configuration. Adhere to CommonJS for compatibility.

This quickstart demonstrates how to set up `knex-migrator` with an SQLite3 database, configure `MigratorConfig.js`, create a basic `init` migration file, and execute the initial migration using the CLI.

/* MigratorConfig.js */ module.exports = { database: { client: process.env.DB_CLIENT || 'sqlite3', connection: { filename: process.env.DB_FILENAME || './dev.sqlite3' } }, migrationPath: __dirname + '/migrations', currentVersion: '1.0' }; /* migrations/init/1-create-users-table.js */ exports.up = function (knex) { return knex.schema.createTable('users', function (table) { table.increments('id').primary(); table.string('name').notNullable(); table.string('email').unique().notNullable(); table.timestamps(true, true); }); }; exports.down = function (knex) { return knex.schema.dropTable('users'); }; // To run: // 1. Install `knex` and `knex-migrator`, e.g., `npm install knex sqlite3 knex-migrator` // 2. Create `MigratorConfig.js` and `migrations/init/1-create-users-table.js` as above. // 3. Run initial migration: // npx knex-migrator init // 4. Then run any subsequent migrations (e.g., after adding new migration files to `migrations/versions/1.0/`): // npx knex-migrator migrate

knex-migrator --version

Debug

Known issues

gotchaknex-migrator does not support database replicas directly due to limitations in knex.js. Configure your application to handle replicas outside of the migration process.

fix

Implement replica-aware logic at the application level or use a separate database provisioning tool.

affects: >=1.0.0

gotchaSQLite databases do not support read locks by default, which can lead to concurrency issues if multiple processes try to run migrations simultaneously.

fix

Ensure migrations are run in a single-process, controlled environment, especially when using SQLite.

affects: >=1.0.0

breakingMixing DDL (Data Definition Language) and DML (Data Manipulation Language) statements within a single migration script is highly discouraged, especially in MySQL, where DDL statements implicitly commit transactions. This can lead to partial changes and data inconsistency if an error occurs.

fix

Separate DDL and DML operations into distinct migration scripts or use transactional blocks carefully for DML within DDL if absolutely necessary and database client supports it without implicit commits.

affects: >=1.0.0

gotchaIf the migration process terminates unexpectedly (e.g., process crash), the migration lock in the database might not be released. This prevents further migrations until manually cleared.

fix

Manually release the lock by running `knex-migrator rollback --force` (if you are sure about the state) or by directly inspecting and clearing the `migrations_lock` table in the database. Always check the database state first.

affects: >=1.0.0

gotchaIt is highly recommended to implement both `up` (for applying) and `down` (for reverting) functions in every migration script. This ensures a reliable and complete rollback capability.

fix

Always provide a `down` function that logically reverses the changes made by the `up` function in your migration files.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Migration lock already exists. Please run 'knex-migrator rollback' or delete the lock table manually.

A previous migration process died or was interrupted, leaving a lock entry in the database.

fix

Run `npx knex-migrator rollback --force` to try and clear the lock and potentially revert partially applied migrations, or manually inspect and clear the `migrations_lock` table.

Error: connect ECONNREFUSED 127.0.0.1:<PORT>

The database server is not running, is inaccessible, or the connection details in `MigratorConfig.js` are incorrect.

fix

Verify that the database server is running and reachable from the application's host, and double-check all connection parameters (host, port, user, password, database name) in `MigratorConfig.js`.

Error: Knex client not installed: <client_name>. Install by: npm install <client_name>

The specified `client` in `MigratorConfig.js` (e.g., 'mysql2', 'sqlite3') does not have its corresponding npm package installed.

fix

Install the necessary database client driver using `npm install <client_name>` or `yarn add <client_name>`.

Error: No MigratorConfig.js found in the current directory or specified path.

The `MigratorConfig.js` file is missing, misspelled, or located in a directory not discoverable by `knex-migrator`.

fix

Ensure `MigratorConfig.js` is present in the project root or specify its path using the `--mgpath` CLI option.

Upgrade

Version history

5.3.2latest on npm

Audit

Dependencies

knexrequiredCore database query builder and migration engine. Required for database interaction and schema manipulation. Specific client drivers (e.g., `mysql2`, `sqlite3`) are also needed depending on the database choice.

mysql2optionalRequired if using MySQL as the database client for Knex.

sqlite3optionalRequired if using SQLite3 as the database client for Knex.

Agent activity

7 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/knex-migrator ↗