Lightweight migration runner with registry, validation, progress, and rollback support
npm install @md-oss/migrationsLightweight migration framework with registry, runner, progress tracking, validation, and rollback support.
- Registry & Discovery – Register migrations manually or auto-discover from files
- Runner – Execute pending migrations with optional dry-run, timeouts, and rollback
- Validation – Pre-flight validation hooks with warnings
- Progress Tracking – Built-in progress logger for long-running jobs
- Rich Errors – Specific error classes for duplicates, timeouts, rollbacks, and validation
- Typed Contracts – Strongly-typed migration context and results
``bash`
pnpm add @md-oss/migrations
`typescript
import { MigrationRegistry, MigrationRunner, createDefaultLogger } from '@md-oss/migrations';
import type { Migration } from '@md-oss/migrations';
import crypto from 'node:crypto';
// 1) Define a migration
const addUsersIndex: Migration = {
name: '2026-01-27-add-users-index',
description: 'Add index on users(email)',
async isCompleted() {
return false; // check DB metadata
},
async isFailing() {
return false;
},
async hasFailed() {
return false;
},
async markComplete() {},
async markFailed(_ctx, _err) {},
async markRollback() {},
async up(ctx) {
ctx.logger.info('Running migration logic');
// apply changes here
},
async down(ctx) {
ctx.logger.info('Rolling back migration');
// rollback changes here
},
async validate() {
return { valid: true };
},
};
// 2) Register migrations
const registry = new MigrationRegistry();
registry.register(addUsersIndex);
// 3) Run pending migrations
const runner = new MigrationRunner(registry, {
logger: createDefaultLogger(),
metadata: { runId: crypto.randomUUID(), startedAt: new Date() },
dryRun: false,
});
await runner.runPending({ skipCompleted: true });
`
`typescript
import path from 'node:path';
const registry = new MigrationRegistry({ debug: true });
await registry.discoverFrom(path.join(process.cwd(), 'migrations'), {
pattern: /\.migration\.(ts|js)$/,
recursive: true,
});
`
- skipCompleted – Skip migrations already marked complete (default: true)continueOnError
- – Keep running remaining migrations when one failstimeout
- – Fail a migration if it exceeds the timeout (ms)dryRun
- – Execute without calling markComplete / markFailed
`typescript
import { MigrationProgress, createDefaultLogger } from '@md-oss/migrations';
const progress = new MigrationProgress(createDefaultLogger(), 1_000);
for (let i = 0; i < 1_000; i++) {
// do work
progress.increment();
}
progress.complete();
``
- MigrationAlreadyRunningError
- MigrationAlreadyCompletedError
- MigrationValidationError
- MigrationExecutionError
- MigrationRollbackError
- MigrationNotRollbackableError
- MigrationNotFoundError
- MigrationTimeoutError
- DuplicateMigrationError
- MigrationRegistry – register, discover, get, list migrations
- MigrationRunner – run/rollback migrations; run pending
- MigrationProgress – log long-running work
- createDefaultLogger / ConsoleLogger – colorful console logging
- Types: Migration, RunOptions, MigrationResult, MigrationStatus, MigrationSystemStatus, MigrationLogger