db-migrate vs migrate: Architecture, DX, and Control Compared

Both db-migrate and migrate solve the same core problem: keeping your database schema in sync with your code over time. However, they take very different approaches to get there. db-migrate acts as a full-featured framework with built-in drivers and a powerful CLI, while migrate is a lean library that gives you the execution engine and expects you to bring the rest. Let's look at how they handle real-world engineering scenarios.

🛠️ Setup and Configuration: Convention vs. Minimalism

db-migrate relies on a configuration file (usually database.json) to define environments, drivers, and connection details. It comes with a built-in CLI that reads this config to manage everything.

# db-migrate: Initialize a project
npx db-migrate init

# Creates a database.json file with sections for dev, test, prod

// db-migrate: database.json
{
  "dev": {
    "driver": "pg",
    "user": "dev_user",
    "database": "my_app_dev"
  }
}

migrate has no required config file format. You typically create a simple JS file to configure the storage mechanism (where migration state is saved) and the directory containing migration files.

// migrate: config.js
const { Store, Migrator } = require('migrate');
const fs = require('fs');

// Define your own storage logic (e.g., a JSON file or DB table)
const store = new Store({
  path: './migrations.json',
  fs: fs
});

const migrator = new Migrator({
  store: store,
  migrationsDirectory: './db/migrations'
});

📜 Creating Migrations: Scaffolding vs. Manual Files

db-migrate shines with its scaffolding CLI. It generates boilerplate code with up and down functions tailored to your specific database driver.

# db-migrate: Generate a new migration
npx db-migrate create add-users-table

// db-migrate: Generated file (e.g., 20231027123456-add-users-table.js)
exports.up = function(db) {
  return db.createTable('users', {
    id: { type: 'int', primaryKey: true, autoIncrement: true },
    email: { type: 'string', unique: true }
  });
};

exports.down = function(db) {
  return db.dropTable('users');
};

migrate does not generate files. You create a JS file manually in your migrations folder. The API is generic; you use your own database client (like pg or mysql2) inside the functions.

// migrate: Manual file (e.g., 001-add-users-table.js)
const db = require('./db-client'); // Your custom DB connection

exports.up = async function(next) {
  await db.query('CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT UNIQUE)');
  next();
};

exports.down = async function(next) {
  await db.query('DROP TABLE users');
  next();
};

🚀 Running Migrations: Built-in CLI vs. Programmatic Control

db-migrate provides a rich CLI for all operations. You can run, rollback, reset, and check status directly from the terminal.

# db-migrate: Run all pending migrations
npx db-migrate up

# db-migrate: Rollback the last migration
npx db-migrate down

# db-migrate: Reset database (down then up)
npx db-migrate reset

migrate includes a basic CLI, but its real strength is programmatic usage. You often write a custom script (e.g., npm run migrate) to run the migrator, giving you full control over error handling and logging.

// migrate: Custom run script (run.js)
const { Migrator } = require('migrate');
const config = require('./config');

async function run() {
  try {
    await config.migrator.up();
    console.log('Migrations completed successfully');
  } catch (err) {
    console.error('Migration failed:', err);
    process.exit(1);
  }
}

run();

# migrate: Execute via custom script
node run.js

🔄 Rollbacks and State Management

db-migrate tracks state in a dedicated table within your database (e.g., migrations). It knows exactly which migrations ran and in what order, allowing reliable rollbacks using the down export in each file.

// db-migrate: Explicit down function required for rollback
exports.down = function(db) {
  // Must reverse the 'up' operation exactly
  return db.removeColumn('users', 'age');
};

migrate stores state wherever you tell it to (a JSON file, a DB table, etc.). Rollbacks are possible but rely entirely on you implementing the down logic correctly. The library simply executes the down function of the specific migration you target.

// migrate: Manual rollback execution
await config.migrator.down('001-add-users-table.js');

🌐 Database Support: Multi-Driver vs. Bring-Your-Own

db-migrate supports a wide range of databases out of the box (PostgreSQL, MySQL, SQLite, MongoDB, Redis, etc.) by using official driver plugins. You just install the driver package (e.g., db-migrate-pg) and update your config.

# db-migrate: Install PostgreSQL driver
npm install db-migrate-pg

migrate is database-agnostic because it doesn't talk to the database itself. You use whatever client library you prefer (pg, mongoose, knex) inside your migration files. This offers maximum flexibility but requires more setup code.

// migrate: Using any client library
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

exports.up = async function(next) {
  const client = await pool.connect();
  try {
    await client.query('CREATE TABLE ...');
  } finally {
    client.release();
  }
  next();
};

🤝 Similarities: Shared Ground

Despite their differences, both libraries share core concepts essential for safe database evolution.

1. Sequential Execution

Both ensure migrations run in a strict order based on filenames or timestamps, preventing race conditions where tables are created after data is inserted.

// Both enforce order: 001-create-users.js runs before 002-add-email.js

2. Up/Down Pattern

Both rely on the standard up (apply change) and down (revert change) function exports to manage schema evolution and rollbacks.

// Both use this pattern
exports.up = function(...) { ... };
exports.down = function(...) { ... };

3. Idempotency Expectations

While neither forces it, both expect developers to write migrations that can handle being run in a controlled environment, often requiring checks to avoid errors if a migration is accidentally run twice.

// Common practice in both
// CREATE TABLE IF NOT EXISTS users ... 

📊 Summary: Key Differences

💡 The Big Picture

db-migrate is like a Swiss Army Knife 🇨🇭—it has every tool you might need built right in. It's perfect for enterprise applications where standardization, multi-db support, and a strong CLI are non-negotiable. If you want to hit the ground running with minimal custom code, this is your choice.

migrate is like a set of high-quality raw materials 🧱—it gives you the core engine to execute migrations but leaves the design of the house up to you. It's ideal for developers who already have a preferred database client, want to keep dependencies low, or need to embed migration logic into a custom deployment pipeline.

Final Thought: If you need a solution that "just works" with heavy lifting done for you, pick db-migrate. If you value simplicity and want to own every line of your migration runner, pick migrate.