@md-oss/migrations

Lightweight migration framework with registry, runner, progress tracking, validation, and rollback support.

Features

• 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

Installation

pnpm add @md-oss/migrations

Quick Start

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 });

Discover Migrations from Files

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,
});

Runner Options

• skipCompleted – Skip migrations already marked complete (default: true)
• continueOnError – Keep running remaining migrations when one fails
• timeout – Fail a migration if it exceeds the timeout (ms)
• dryRun – Execute without calling markComplete / markFailed

Progress Tracking

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();

Error Types

• MigrationAlreadyRunningError
• MigrationAlreadyCompletedError
• MigrationValidationError
• MigrationExecutionError
• MigrationRollbackError
• MigrationNotRollbackableError
• MigrationNotFoundError
• MigrationTimeoutError
• DuplicateMigrationError

API Surface

• 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