@multisystemsuite/db-migrator

Versioned SQL migrations with rollbacks, dry-run, checksums, validation, and migration history. Supports any database your SQL targets (MySQL, PostgreSQL, SQL Server, etc.).

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/db-migrator on npm

Installation

pnpm add @multisystemsuite/db-migrator

Quick start

import { DbMigrator } from '@multisystemsuite/db-migrator';

const migrator = new DbMigrator({
  migrationsDir: './migrations',
  dialect: 'postgresql',
});

await migrator.up({
  executor: async (sql) => {
    await pool.query(sql);
  },
});

CLI equivalent:

db-toolkit migrate create -n add_users_index
db-toolkit migrate up
db-toolkit migrate down

Migration file format

File name: {timestamp}_{name}.sql

-- Migration: add_users_index
-- @multisystemsuite/db-migrator

-- UP
CREATE INDEX idx_users_email ON users(email);

-- DOWN
DROP INDEX idx_users_email ON users;

Configuration

| Option | Default | Description | |--------|---------|-------------| | migrationsDir | required | Directory for .sql files | | historyFile | {dir}/.migration-history.json | Applied migration log | | dialect | postgresql | Metadata label |

API reference

| Method | Description | |--------|-------------| | create(name) | Create new migration file; returns path | | discoverMigrations() | List migration files with parsed UP/DOWN | | getPendingMigrations() | Migrations not yet applied | | up({ dryRun?, executor? }) | Apply pending migrations | | down({ dryRun?, executor? }) | Roll back last applied migration | | loadHistory() / saveHistory() | Read/write history JSON | | getHistory() | Applied MigrationRecord[] | | validateMigration(file) | Ensure UP and DOWN are non-empty |

MigrateResult

{ applied: string[]; skipped: string[]; dryRun: boolean }

Dry run

await migrator.up({ dryRun: true });
// Lists what would run without executing or saving history

History & checksums

Each applied migration stores:

• id, name, checksum (SHA-256 of file content)
• appliedAt, optional rolledBackAt

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/db-migrator
• Install: npm install @multisystemsuite/db-migrator