Registry / devops / abstract-migrate

abstract-migrate

library2.4.0jsnpmunverified

A storage-agnostic migration runner (v2.4.0) that allows you to run scripts (e.g., database migrations) exactly once. Unlike most migration tools tied to specific databases, Abstract Migrate lets you write your own storage engine (filesystem, PostgreSQL, etc.) by implementing five simple functions: load, add, remove, acquireLock, and releaseLock. It provides a CLI (`am`) for creating, listing, and running migrations. Release cadence is irregular; latest version is from 2019. Differentiators: lock-based concurrency safety, callback/promise engine interface, JSON config file.

devops database

npm install abstract-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ABSTRACT-MIGRATE

abstract-migrate

devopsjavascriptv2.4.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.

abstract-migrate (CLI)

✓ npm i -g abstract-migrate

✗ npm i abstract-migrate --save

Install globally for CLI usage.

createMigration

✓ import { createMigration } from 'abstract-migrate';

✗ const createMigration = require('abstract-migrate').createMigration;

Library exports named functions; prefers ESM but CJS also works.

runMigrations

✓ import { runMigrations } from 'abstract-migrate';

✗ const am = require('abstract-migrate'); am.runMigrations();

Direct named import avoids namespace ambiguity.

Global install, configuration, custom engine implementation, migration creation, and running all pending migrations.

// 1. Install globally // npm i -g abstract-migrate // 2. Create a config file .abstract-migrate.json { "engine": "./myEngine.js", "migrationPath": "./migrations" } // 3. Write a custom engine (e.g., file-based) const fs = require('fs'); const path = require('path'); const storePath = './migration-store.json'; module.exports = { load: function() { if (!fs.existsSync(storePath)) return []; return JSON.parse(fs.readFileSync(storePath, 'utf8')); }, add: function(migrations) { const existing = this.load(); const merged = existing.concat(migrations); fs.writeFileSync(storePath, JSON.stringify(merged, null, 2)); }, remove: function(migrations) { const existing = this.load(); const names = new Set(migrations.map(m => m.name)); const filtered = existing.filter(m => !names.has(m.name)); fs.writeFileSync(storePath, JSON.stringify(filtered, null, 2)); }, acquireLock: function() { return true; }, releaseLock: function() { return true; } }; // 4. Create a migration // mkdir migrations && am create my-first-migration // 5. Run pending migrations // am up

Debug

Known issues

gotchaEngine's acquireLock must be atomic to avoid race conditions between simultaneous runs.

fix

Use a database-level advisory lock or file locking to ensure only one process acquires the lock at a time.

affects: *

breakingIn v2.0.0, the engine API changed from callback-based to promise-or-callback. If you use callbacks, the last argument is a callback; if you return a promise, the callback is ignored.

fix

Ensure engines either return a promise OR call the callback (not both).

affects: >=2.0.0 <3.0.0

deprecatedCLI flag --ignore-past (-p) may be removed in future versions.

fix

Use --ignore-past or -p as documented; no replacement announced yet.

affects: >=2.0.0

gotchaIf migrationPath directory does not exist, 'am list' and 'am up' will crash with a file-not-found error.

fix

Create the migrations directory before running commands: mkdir -p migrations

affects: *

Errors

Common errors & fixes

Error: Cannot find module './engine.js'

The engine path in .abstract-migrate.json is relative to the current working directory, not the config file location.

fix

Use an absolute path or ensure the path is relative to where you run the command.

ReferenceError: require is not defined

Using 'require' in an ESM context (e.g., 'type': 'module' in package.json).

fix

Rename engine file to .cjs or use dynamic import() inside the engine.

Error: Migration 1492708337968-my-cool-migration already run

Duplicate migration name detected; migration names must be unique over time.

fix

Use timestamps or UUIDs in migration filenames to ensure uniqueness.

Upgrade

Version history

2.4.0latest on npm

Audit

Dependencies

yargsrequiredCLI argument parsing

globrequiredFile pattern matching for migration files

chalkrequiredColored terminal output

lodashrequiredUtility functions

Agent activity

53 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bharley/abstract-migrate ↗

packageabstract-migrate ↗

homepagehttps://github.com/bharley/abstract-migrate#readme ↗