Umzug is a robust, framework-agnostic migration tool designed for Node.js environments, providing a clean and programmatic API for managing database or application migrations. The current stable version is 3.8.2. It maintains a consistent release cadence with frequent patch updates and minor versions introducing new features or improvements. Key differentiators include its TypeScript-first approach with built-in typings, auto-completion, and IDE documentation, a powerful programmatic API, a built-in CLI, and its database-agnostic design. It supports logging of migration processes and offers flexibility with multiple storage options for migration data, such as database-backed storage (e.g., SequelizeStorage) or file-based storage. While frequently used with Sequelize, Umzug is not coupled to any specific ORM or database, making it highly adaptable for various project needs.
npm install umzugVerified import paths — ran on the pinned version, not inferred.
This quickstart initializes a SQLite database with Sequelize, sets up Umzug to manage migrations using `SequelizeStorage`, creates a sample migration file dynamically, and then executes the 'up' command to apply pending migrations. It demonstrates basic setup for both JavaScript and TypeScript users (though written as ESM-enabled JS for broader compatibility), including how Umzug interacts with a database context and logs its operations. It also includes an optional verification step to check for table creation.
Refer to the 'Upgrading from v2.x' section in the official Umzug documentation for a detailed migration guide. This often involves changes to the configuration object and migration file structure.
Review migration glob patterns if encountering issues after upgrading to v3.8.0+. `fast-glob` is generally more performant and robust, so changes should be minimal or beneficial.
For ESM support, ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions. When using `ts-node` for TypeScript migrations, ensure `tsconfig.json` has `"module": "NodeNext"` or `"module": "ESNext"` and `"target": "ESNext"` along with `"moduleResolution": "NodeNext"` for correct resolution of `import` statements. You might need to `require('ts-node/register')` explicitly for `.ts` files to run.Upgrade Umzug to version 3.6.0 or higher to include the fix for `DeprecationWarning` with Sequelize V7. Ensure your Sequelize version is also up-to-date and compatible.
Install `fast-glob` as a dependency: `npm install fast-glob`. If using an older Umzug version (before 3.8.0), ensure `glob` is installed: `npm install glob`.
Refactor your code to use `import` statements instead of `require`. For example, `const { Umzug } = require('umzug')` should become `import { Umzug } from 'umzug'`. If mixing CJS and ESM, consider dynamic `import()` or ensuring your files are correctly demarcated.Ensure that `sequelize` is a properly initialized instance of the Sequelize class: `const sequelize = new Sequelize({ /* config */ });`. Verify that `sequelize.getQueryInterface()` is called on a valid object before passing it to Umzug's `context` option.