Registry / database / umzug
library3.8.2jsnpmunverified

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 umzug
INSTALL
IMPORT
SIG · UMZUG
U
umzug
databasejavascriptv3.8.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Umzug
import { Umzug } from 'umzug'
const Umzug = require('umzug')
While CommonJS `require` works for older Node.js projects, the library encourages and is optimized for ESM `import`s, especially since v3.5.0 which introduced non-breaking ESM support. The main class for creating migration instances.
SequelizeStorage
import { SequelizeStorage } from 'umzug'
const { SequelizeStorage } = require('umzug')
A specific storage implementation for persisting migration state in a Sequelize-compatible database. Use this when integrating with Sequelize ORM. Similar `import`/`require` considerations as `Umzug`.
Migration (type)
import type { Migration } from 'umzug'
import { Migration } from 'umzug'
For TypeScript projects, `Migration` is a type helper exposed by Umzug to correctly type the `context` argument within migration functions. Always use `import type` to avoid bundling unnecessary runtime code.

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.

import { Sequelize } from 'sequelize'; import { Umzug, SequelizeStorage } from 'umzug'; import { join, dirname } from 'path'; import { fileURLToPath } from 'url'; import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs'; const __dirname = dirname(fileURLToPath(import.meta.url)); const dbPath = join(__dirname, 'db.sqlite'); const migrationsDir = join(__dirname, 'migrations'); // Ensure migrations directory exists if (!existsSync(migrationsDir)) { mkdirSync(migrationsDir, { recursive: true }); } // Create a dummy migration file for demonstration const migrationContent = ` const { DataTypes } = require('sequelize'); async function up({ context: queryInterface }) { await queryInterface.createTable('users', { id: { type: DataTypes.INTEGER, allowNull: false, primaryKey: true, autoIncrement: true }, name: { type: DataTypes.STRING, allowNull: false, }, createdAt: { type: DataTypes.DATE, allowNull: false, }, updatedAt: { type: DataTypes.DATE, allowNull: false, }, }); } async function down({ context: queryInterface }) { await queryInterface.dropTable('users'); } module.exports = { up, down }; `; const migrationFilePath = join(migrationsDir, '00_initial.js'); if (!existsSync(migrationFilePath)) { writeFileSync(migrationFilePath, migrationContent); } const sequelize = new Sequelize({ dialect: 'sqlite', storage: dbPath, logging: false // Suppress sequelize logs for cleaner output }); const umzug = new Umzug({ migrations: { glob: join(migrationsDir, '*.js') }, context: sequelize.getQueryInterface(), storage: new SequelizeStorage({ sequelize }), logger: console, }); (async () => { console.log('Running Umzug migrations...'); await umzug.up(); console.log('Migrations complete.'); // Optional: Verify table creation try { const [results] = await sequelize.query("SELECT name FROM sqlite_master WHERE type='table' AND name='users';"); if (results.length > 0) { console.log('Table "users" exists in the database.'); } else { console.log('Table "users" does NOT exist.'); } } catch (error) { console.error('Error verifying table:', error.message); } // Optional: Rollback example // console.log('Rolling back migrations...'); // await umzug.down(); // console.log('Rollback complete.'); await sequelize.close(); })();
umzug --version
Debug
Known issues
breakingUmzug v3.x introduced several breaking changes from v2.x. Users upgrading from v2.x must consult the official upgrade guide to adapt their migration scripts and configuration.
fix
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.
affects: >=3.0.0
breakingThe internal glob library was switched from `glob` to `fast-glob` in v3.8.0. While this is unlikely to cause issues for most users, highly specific glob patterns might behave slightly differently.
fix
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.
affects: >=3.8.0
gotchaUmzug v3.5.0 introduced non-breaking ESM support, meaning it can be used with `import` statements in ES Modules. However, older Node.js projects or those using `ts-node` without proper configuration might still face issues with module resolution if not explicitly configured for ESM.
fix
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.
affects: >=3.5.0
gotchaWhen using Umzug with Sequelize v7, a `DeprecationWarning` might occur if older Sequelize integration patterns are used. This was specifically addressed in Umzug v3.6.0.
fix
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.
affects: >=3.0.0 <3.6.0
Errors
Common errors & fixes
Error: Cannot find module 'glob' or 'fast-glob'
The module loader cannot find the glob package, possibly due to a missing dependency or an incorrect import/usage. Umzug migrated from `glob` to `fast-glob` in v3.8.0.
fix
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`.
TypeError: require is not a function in ES module scope
Attempting to use `require` in an ES Module (`.mjs` file or `"type": "module"` in `package.json`) where `require` is not globally available.
fix
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.
TypeError: Cannot read properties of undefined (reading 'getQueryInterface')
The `context` provided to Umzug is not an instance of Sequelize or does not have a `getQueryInterface` method, or `sequelize` itself is undefined/null.
fix
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.
Upgrade
Version history
3.8.2latest on npm
Audit
Dependencies
sequelizeoptionalCommonly used for database interactions and provides the `SequelizeStorage` mechanism. While Umzug is framework-agnostic, Sequelize integration is a primary use case.
fast-globrequiredUsed internally for glob pattern matching to find migration files, replacing `glob` since v3.8.0.
ts-nodeoptionalRequired to run TypeScript migration files directly in a Node.js environment without prior compilation.
Agent activity
40 hits · last 30 days
node
34
OpenAI (training)
2
Resources