@wuyuchentr/database-migration-tool

Database migration tool with version control, transactions, locking, and rollback. Zero core dependencies (optional driver packages).

Flyway-inspired, umzug alternative. Supports SQLite, MySQL, PostgreSQL.

Install

npm install @wuyuchentr/database-migration-tool

For SQLite (built-in support for Node 22+ node:sqlite):

# Optional, for better performance:
npm install better-sqlite3

For MySQL:

npm install mysql2

For PostgreSQL:

npm install pg

CLI

# Create a new migration
npx migrate create add_users_table
# → Created: ./migrations/20250101000123_add_users_table.up.sql
#                   ./migrations/20250101000123_add_users_table.down.sql

# Apply pending migrations
npx migrate up

# Apply up to a specific target
npx migrate up --target=20250101000123

# Rollback
npx migrate down
npx migrate down --step=3

# Check status
npx migrate status

# Run seed files
npx migrate seed
npx migrate seed users.sql posts.sql

API

const { Migrator } = require('@wuyuchentr/database-migration-tool');

const migrator = new Migrator({
  driver: 'sqlite',       // 'sqlite' | 'mysql' | 'postgres'
  database: './app.db',   // SQLite path, or MySQL/PG database name
  directory: './migrations',
  table: '_migrations',   // migration history table name
});

await migrator.connect();

// Run migrations
const count = await migrator.up();
const count = await migrator.up({ target: '20250101000123' });

// Rollback
const count = await migrator.down({ step: 1 });

// Create migration
const { name, up, down } = await migrator.create('add_posts_table');

// Status
const rows = await migrator.status();
// [{ name, timestamp, executed, hash }, ...]

// Seeds
await migrator.seed('users.sql');

await migrator.disconnect();

Config file

Create migrate.config.js or migrate.json in your project root:

{
  "driver": "sqlite",
  "database": "./data/app.db",
  "directory": "./db/migrations",
  "seedDirectory": "./db/seeds",
  "table": "my_migrations"
}

Migration files

migrations/
├── 20250101000123_add_users_table.up.sql
├── 20250101000123_add_users_table.down.sql
├── 20250201000123_add_posts_table.up.sql
├── 20250201000123_add_posts_table.down.sql
└── seeds/
    ├── 001_admin_user.sql
    └── 002_sample_data.sql

Each migration must have a paired up/down file.

How it works

1. Creates a _migrations table to track applied migrations
2. On up: reads pending .up.sql files in order, executes within a transaction, records hash
3. On down: executes .down.sql within a transaction, removes record
4. Transaction wrapping ensures atomicity — partial migrations roll back cleanly
5. Locking via driver-specific mechanisms prevents concurrent migration runs