# Initialize dbmate in project root
dbmate new create_users_table
# Output: migrations/20231027120000_create_users_table.sql

-- migrations/20231027120000_create_users_table.sql

-- +migrate Up
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_users_email ON users(email);

-- +migrate Down
DROP TABLE IF EXISTS users;

import { execSync, spawn } from 'child_process';
import { exit } from 'process';

interface MigrationConfig {
  data

baseUrl: string; migrationsDir: string; dryRun: boolean; }

export async function runMigrations(config: MigrationConfig): Promise<void> { const { databaseUrl, migrationsDir, dryRun } = config;

console.log([Migration] Starting migration process...);

try { // Validate connection before attempting migration execSync(dbmate --url "${databaseUrl}" --migrations-dir "${migrationsDir}" ping, { stdio: 'inherit' });

if (dryRun) {
  console.log('[Migration] Dry run mode enabled. Validating SQL syntax.');
  // dbmate does not have a native dry-run for execution, 
  // but we can parse files or use --dry-run if supported by fork
  // Here we assume standard execution with transaction wrapping
}

// Execute migrations
// dbmate automatically wraps migrations in transactions where supported
execSync(`dbmate --url "${databaseUrl}" --migrations-dir "${migrationsDir}" up`, {
  stdio: 'inherit'
});

console.log('[Migration] Schema update successful.');

} catch (error) { console.error('[Migration] Migration failed. Rolling back...'); // In a real pipeline, trigger rollback or alerting exit(1); } }

// Usage in CI/CD script // runMigrations({ // databaseUrl: process.env.DATABASE_URL!, // migrationsDir: './migrations', // dryRun: false // });

#### 4. Zero-Downtime Migration Example
Applying the Expand/Contract pattern for adding a `status` column.

**Migration 1: Add Column**
```sql
-- +migrate Up
ALTER TABLE users ADD COLUMN status TEXT DEFAULT 'active';
-- Note: Using DEFAULT avoids table rewrite in PostgreSQL. 
-- For MySQL, use pt-online-schema-change or gh-ost for large tables.

-- +migrate Down
ALTER TABLE users DROP COLUMN status;

Deployment Sequence:

1. Merge Migration 1.
2. Deploy Application v1.0: Code reads/writes status but handles NULL gracefully.
3. Run Migration 1 via CI/CD.
4. Deploy Application v1.1: Code enforces status constraints and removes fallback logic.
5. (Optional) Migration 2: Add NOT NULL constraint and backfill index once v1.1 is stable.

Pitfall Guide

1. Non-Idempotent Migrations

Mistake: Writing migrations that fail if run twice (e.g., CREATE TABLE without IF NOT EXISTS in contexts where re-execution is expected, or missing down logic). Impact: CI/CD pipelines fail on retries, leading to partial deployments and manual intervention. Best Practice: Use tools that enforce idempotency. Ensure every migration has a corresponding Down block for rollback capability.

2. Table Locking on Large Datasets

Mistake: Running ALTER TABLE on tables with >10M rows without considering lock duration. Impact: Application hangs; API latency spikes to timeout levels; health checks fail; cascading outages. Best Practice: For PostgreSQL, use CONCURRENTLY for indexes. For MySQL, integrate gh-ost or pt-online-schema-change for structural changes. Always test migration duration against production data volumes in staging.

3. Missing Advisory Locks

Mistake: Allowing parallel CI/CD jobs to run migrations simultaneously. Impact: Race conditions cause duplicate execution or schema corruption. Best Practice: Ensure your tool uses advisory locks (e.g., PostgreSQL pg_advisory_lock) to serialize migration runs. If using custom runners, implement distributed locking via Redis or database locks.

4. Data Migration Without Feature Flags

Mistake: Combining schema changes and data transformations in a single deployment without feature toggles. Impact: If the data migration fails, the schema is altered, and rollback is complex. Old code versions may break immediately. Best Practice: Decouple schema changes from data migrations. Use feature flags to control data transformation logic. Perform data migrations in background jobs with idempotency keys.

5. Ignoring Connection Timeouts

Mistake: Migrations hanging due to connection pool exhaustion or network timeouts. Impact: Deployment appears stuck; database connections leak; service degradation. Best Practice: Configure migration timeouts explicitly. Ensure the migration tool uses a dedicated connection or respects pool limits. Monitor connection counts during migration execution.

6. Environment Drift

Mistake: Running migrations manually in production or having different migration states across replicas. Impact: "Works on my machine" bugs; read replicas diverge; debugging requires schema comparison tools. Best Practice: Migrations must run automatically via CI/CD. No manual execution allowed. Use infrastructure-as-code to ensure environment parity.

7. The "Phantom Column" Anti-Pattern

Mistake: Dropping a column while older application instances are still running. Impact: Runtime errors in running pods; requests fail until the deployment completes. Best Practice: Never drop columns in the same deployment as the code that stops using them. Always follow Expand/Contract: Add -> Deploy Code -> Migrate -> Deploy New Code -> Drop.

Production Bundle

Action Checklist

• Idempotency Verification: Confirm all migrations can be applied and rolled back safely multiple times.
• Expand/Contract Compliance: Review PRs for breaking changes; ensure backward compatibility is maintained during deployment.
• CI/CD Integration: Migrations run automatically in the pipeline; manual execution is disabled.
• Locking Strategy: Verify advisory locks are active to prevent concurrent migration runs.
• Rollback Testing: Validate that Down migrations restore the database to the previous state in a staging environment.
• Performance Baseline: Test migration duration on a production-sized data dump; set alerts for long-running migrations.
• Connection Management: Ensure migration tools use appropriate connection pooling and timeout settings.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup / Small DB (<10GB)	ORM Migrations	Low overhead; rapid iteration; sufficient for scale.	Low
Mid-Sized SaaS / Polyglot	CLI Tool (dbmate/Flyway)	Language agnostic; robust versioning; transactional safety.	Medium
High Traffic / Large Tables (>1TB)	OSC Tools (gh-ost/pt-osc) + CLI	Zero-downtime structural changes; prevents lock contention.	High
Data Warehouse / Analytics	ETL Pipelines (dbt)	Schema evolution tied to data transformation logic; testing built-in.	Medium
Multi-Tenant SaaS	Tenant-aware Migrations	Isolated schema changes per tenant; requires sharding-aware tooling.	High

Configuration Template

dbmate Configuration (.env)

# Database URL for migration tool
DATABASE_URL=postgres://user:password@localhost:5432/myapp?sslmode=disable

# Optional: Custom migrations directory
DBMATE_MIGRATIONS_DIR=./migrations

# Optional: Schema version table name
DBMATE_SCHEMA_TABLE=schema_migrations

GitHub Actions Integration

name: Database Migration
on:
  push:
    branches: [main]

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dbmate
        run: |
          curl -fsSL https://github.com/amacneil/dbmate/releases/latest/download/dbmate-linux-amd64 -o dbmate
          chmod +x dbmate
          sudo mv dbmate /usr/local/bin/dbmate
      - name: Run Migrations
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: dbmate up
      - name: Verify Schema
        run: dbmate dump > schema.sql

Quick Start Guide

1. Install Tool: Run npm install -g dbmate or download the binary for your OS.
2. Initialize: Run dbmate new init to create the schema version table in your database.
3. Create Migration: Run dbmate new create_table_name to generate a timestamped SQL file.
4. Write SQL: Edit the generated file to add -- +migrate Up and -- +migrate Down blocks.
5. Apply: Run dbmate up to execute pending migrations. Verify with dbmate status.

Database migration tools are not merely convenience utilities; they are the control plane for your data integrity. By adopting language-agnostic tools, enforcing idempotency, and implementing the Expand/Contract pattern, engineering teams can achieve zero-downtime schema evolution and eliminate migration-related outages. Treat migrations as first-class citizens in your deployment pipeline to ensure scalability and reliability.