immigration

library2.3.0jsnpmunverified

Simple, no-frills database migration utility for Node.js. Version 2.3.0, stable, with low release cadence. Provides CLI commands for up, down, create, list, executed, log, unlog, and tidy migrations. Supports plugin adapter architecture for persisting migration state (built-in fs adapter). Lightweight alternative to node-migrate or db-migrate, with optional async (callback/promise) migration scripts. Lacks built-in database-specific adapters; requires custom adapters for most databases.

database devops

npm install immigration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IMMIGRATION

immigration

databasejavascriptv2.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

immigration CLI

✓ npx immigration --help

✗ npm install immigration && immigration --help

CLI tool, not a library. Use npx or install globally. There is no programmatic API.

migration file exports

✓ exports.up = function (callback) { callback(); }; exports.down = function () { return Promise.resolve(); };

✗ module.exports = { up: function(cb) {}, down: function(cb) {} };

Both CommonJS and ES module exports work. Functions can be async or return promise.

adapter init

✓ module.exports = { init: function() { return { isLocked, executed, lock, unlock, log, unlog }; } };

✗ var adapter = require('immigration/fs'); adapter.init();

Adapters are separate packages; the built-in fs adapter is at immigration/fs.

Demonstrates creating a migration file with up/down functions, and running/rolling back migrations via CLI.

// Create a migration file: immigration create add-users // Edit the generated file: migrations/xxxxxxxxxx-add-users.js exports.up = async function () { console.log('Running up migration'); }; exports.down = async function () { console.log('Running down migration'); }; // Run all pending up migrations: // npx immigration up --all // Rollback the last migration: // npx immigration down --count 1

Debug

Known issues

gotchaImmigration is a CLI tool and does not export a programmatic API. Cannot be `require`d as a library.

fix

Use child_process.exec to invoke CLI from Node.js, or consider migration libraries with programmatic API.

affects: >=2.0.0

gotchaRequires an adapter for persistence; default fs adapter stores state in a JSON file in the migration directory.

fix

Ensure --use flag points to an adapter package, or rely on default built-in fs adapter.

affects: >=2.0.0

deprecatedThe built-in fs adapter may be removed in future versions; consider using or creating explicit adapters.

fix

Specify a custom adapter via --use flag, e.g., --use ./my-adapter.js

affects: >=2.0.0

gotchaMigrations are run in lexicographic order of filenames; naming convention matters.

fix

Use timestamps or sequential numbers in filenames (e.g., 01-add-users.js).

affects: >=2.0.0

Errors

Common errors & fixes

Error: No such command "migrate"

Running 'immigration migrate' but correct command is 'up' or 'down'.

fix

Use 'immigration up' or 'immigration down' instead of 'migrate'.

Error: Adapter "undefined" is not valid

Missing --use flag when required, or invalid adapter path.

fix

Provide a valid adapter: e.g., --use immigration/fs or a custom adapter module.

Cannot find module '/path/to/immigration/src/fs.ts'

Using an outdated custom adapter that references internal source file.

fix

Adapter should require 'immigration/fs' (the built-in) or be self-contained; do not rely on internal paths.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubgit://github.com/blakeembrey/node-immigration ↗

packageimmigration ↗

homepagehttps://github.com/blakeembrey/node-immigration ↗