knex-umzug is a storage adapter for the umzug database migration library, designed to integrate umzug with knex.js for database interactions. It allows umzug to persist and manage migration states within a relational database using knex as the underlying query builder. The package is currently stable at version 4.1.1, with releases primarily driven by compatibility updates for umzug and knex, alongside bug fixes. A key feature is its support for namespacing and custom migration table names, which enables multiple isolated migration setups to share the same database while maintaining distinct migration states. Furthermore, it tracks comprehensive migration metadata including the current state, all migration paths, the hostname, and the system user who executed each migration, providing a detailed audit trail. This offers enhanced visibility and control over the migration process compared to simpler storage solutions.
npm install knex-umzugVerified import paths — ran on the pinned version, not inferred.
Demonstrates initializing a Knex.js connection, configuring Umzug with KnexUmzug as its storage adapter, and running migrations. It also includes a runnable setup for a dummy migration file to illustrate the full flow.
Upgrade Node.js to version 12 or higher, or explicitly install `knex-umzug@^3.0.0` if Node.js 8/10 support is required.
Ensure your migration table (default: `migrations`) has an `id` column with a primary key constraint. If upgrading from an older version, review your database schema and add the primary key manually if necessary.
Most users are unlikely to be affected by this. If you encounter issues related to migration history not being found after upgrading from v2.x, ensure your `storageOptions` align with the `KnexUmzug` class constructor expectations rather than older string-based storage options.
For `umzug` v3+, pass an instance of `new KnexUmzug(...)` to the `storage` property of the `Umzug` constructor. For `umzug` v2, pass the string `'knex-umzug'` to `storage` and `storageOptions` to the `Umzug` constructor. Always refer to the `knex-umzug` README for the correct `umzug` version-specific setup.
Configure your `package.json` with `"type": "module"` if all your files are ESM, or use `.mjs` extensions for ESM files. If using CommonJS for migrations, `module.exports.up = ...` will still work, but `umzug` v3+ documentation primarily shows ESM examples.
Ensure you are on `knex-umzug@4.1.1` or higher, especially if you use a custom table name for your `umzug_migrations_table` and encounter schema creation errors for the `id` column.
For TypeScript/ESM projects, use `import { Umzug } from 'umzug';`. For CommonJS, ensure you're using `const { Umzug } = require('umzug');` (note the destructuring) as `umzug` v3 provides a CJS fallback that exports a named `Umzug`.Use `import KnexUmzug from 'knex-umzug';` for ESM/TypeScript. For CommonJS, use `const KnexUmzug = require('knex-umzug');`.Ensure your database user has sufficient permissions to create tables. KnexUmzug will create the table if it doesn't exist upon first `umzug.up()` call, but if there are underlying database connection or permission errors, it might fail silently or with a generic Knex error before reaching this point.
Verify the `connection` details passed to `knex()` constructor are correct, including hostname, port, username, and password. Ensure the database server is running and accessible from where the application is hosted.