CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-db-migrate

Database migration framework for Node.js applications that enables developers to programmatically manage database schema changes and evolution over time.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

cli-interface.mddocs/

CLI Interface

Command-line interface providing comprehensive migration and database management tools. The CLI supports all programmatic operations through terminal commands, making it ideal for development workflows, CI/CD pipelines, and server deployments.

Installation and Usage

Global Installation

# Install globally
npm install -g db-migrate

# Use from anywhere
db-migrate --help

Local Installation

# Install locally
npm install --save db-migrate

# Use via npm scripts or npx
npx db-migrate --help
node node_modules/db-migrate/bin/db-migrate --help

Command Structure

db-migrate [command] [arguments] [options]

Migration Commands

Run Migrations Up

Execute pending migrations to apply schema changes.

# Run all pending migrations
db-migrate up

# Run up to specific migration
db-migrate up [migration-name]

# Run specific number of migrations
db-migrate up -c [count]

# Run with specific environment
db-migrate up --env production

# Run with verbose output
db-migrate up --verbose

# Dry run (show SQL without executing)
db-migrate up --dry-run

Examples:

# Run all pending migrations
db-migrate up

# Run up to specific migration
db-migrate up 20231201120000-add-users-table

# Run only next 3 migrations
db-migrate up -c 3

# Run in production environment
db-migrate up --env production

# Preview changes without executing
db-migrate up --dry-run --verbose

Run Migrations Down

Execute migration rollbacks to undo schema changes.

# Roll back last migration
db-migrate down

# Roll back specific number of migrations
db-migrate down -c [count]

# Roll back with specific environment
db-migrate down --env development

# Roll back with verbose output
db-migrate down --verbose

Examples:

# Roll back last migration
db-migrate down

# Roll back last 3 migrations
db-migrate down -c 3

# Roll back in test environment
db-migrate down --env test

Create Migration

Create new migration files with proper naming and templates.

# Create new migration
db-migrate create [migration-name]

# Create SQL migration
db-migrate create [migration-name] --sql-file

# Create CoffeeScript migration
db-migrate create [migration-name] --coffee-file

# Create conditional migration
db-migrate create [migration-name] --ignore-on-init

Examples:

# Create JavaScript migration
db-migrate create add-users-table

# Create SQL migration
db-migrate create add-indexes --sql-file

# Create migration in specific directory
db-migrate create add-permissions -m ./db/migrations

Check Migration Status

Check pending migrations without executing them.

# Check all pending migrations
db-migrate check

# Check specific number of pending migrations
db-migrate check -c [count]

# Check with specific environment
db-migrate check --env staging

Reset Migrations

Reset database by rolling back all migrations.

# Reset all migrations
db-migrate reset

# Reset with specific environment
db-migrate reset --env test

Sync to Migration

Synchronize database to specific migration state.

# Sync to specific migration
db-migrate sync [migration-name]

# Sync with environment
db-migrate sync [migration-name] --env production

Database Commands

Create Database

Create a new database.

# Create database
db-migrate db:create [database-name]

# Create with specific environment
db-migrate db:create [database-name] --env production

# Create with specific config
db-migrate db:create [database-name] --config ./config/database.json

Examples:

# Create development database
db-migrate db:create myapp_development

# Create production database
db-migrate db:create myapp_production --env production

Drop Database

Drop (delete) an existing database.

# Drop database
db-migrate db:drop [database-name]

# Drop with specific environment
db-migrate db:drop [database-name] --env test

Examples:

# Drop test database
db-migrate db:drop myapp_test

# Drop staging database
db-migrate db:drop myapp_staging --env staging

Seeding Commands

Run Seeds

Execute database seeding operations.

# Run version-controlled seeds (default)
db-migrate seed

# Run version-controlled seeds explicitly
db-migrate seed:vc

# Run static seeds
db-migrate seed:static

# Run seeds with environment
db-migrate seed --env development

Undo Seeds

Rollback seeding operations.

# Undo last seed
db-migrate seed:down

# Undo specific number of seeds
db-migrate seed:down -c [count]

# Undo with environment
db-migrate seed:down --env test

Reset Seeds

Reset all seeds.

# Reset all seeds
db-migrate seed:reset

# Reset with environment
db-migrate seed:reset --env test

Utility Commands

Transition Protocol

Transition migrations to latest protocol version.

# Transition to latest protocol
db-migrate transition

Help

Display help information.

# General help
db-migrate --help
db-migrate -h

# Command-specific help
db-migrate up --help
db-migrate create --help

Command Options

Global Options

These options work with most commands:

# Environment selection
-e, --env [environment]          # Set environment (dev, test, prod, etc.)

# Configuration
-c, --config [path]              # Config file path (default: database.json)
-m, --migrations-dir [path]      # Migrations directory path
--vcseeder-dir [path]           # Version controlled seeds directory
--staticseeder-dir [path]       # Static seeds directory

# Operation control
-c, --count [number]            # Number of migrations/seeds to process
--dry-run                       # Show SQL without executing
--verbose, -v                   # Verbose output
--force-exit                    # Force exit after completion

# Table configuration
-t, --table [name]              # Migration table name
--seeds-table [name]            # Seeds table name

# Transaction control
--non-transactional            # Disable transaction wrapping

# Output control
--log-level [level]             # Set log level (error, warn, info, verbose, debug, silly)

Migration-Specific Options

# File generation options
--sql-file                      # Create SQL migration file
--coffee-file                   # Create CoffeeScript migration file
--ignore-on-init               # Create conditional migration file

# Execution options
--ignore-completed-migrations   # Start from first migration regardless of history

Configuration Files

Default Configuration

db-migrate looks for database.json in the current directory by default:

{
  "development": {
    "driver": "mysql",
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "myapp_development"
  },
  "test": {
    "driver": "mysql",
    "host": "localhost", 
    "user": "test",
    "password": "test",
    "database": "myapp_test"
  },
  "production": {
    "driver": "mysql",
    "host": "prod-db.example.com",
    "user": "prod_user",
    "password": "secure_password",
    "database": "myapp_production"
  }
}

Custom Configuration

# Use custom config file
db-migrate up --config ./config/database.json

# Use different config for different commands
db-migrate up --config ./config/dev-db.json
db-migrate seed --config ./config/seed-db.json

Environment Variables

CLI respects environment variables for configuration:

# Database connection
export DATABASE_URL=mysql://user:pass@host:port/db

# Migration settings
export DB_MIGRATE_TABLE=custom_migrations
export DB_MIGRATE_SEEDS_TABLE=custom_seeds

# Directory paths
export DB_MIGRATE_MIGRATIONS_DIR=./database/migrations
export DB_MIGRATE_SEEDS_DIR=./database/seeds

Workflow Examples

Development Workflow

# Setup development environment
db-migrate db:create myapp_development --env development
db-migrate up --env development
db-migrate seed --env development

# Create and apply new migration
db-migrate create add-products-table
db-migrate up --env development

# Test rollback
db-migrate down -c 1 --env development
db-migrate up --env development

Testing Workflow

# Setup test environment
db-migrate db:create myapp_test --env test
db-migrate up --env test
db-migrate seed:static --env test

# Reset for clean tests
db-migrate reset --env test
db-migrate up --env test
db-migrate seed:static --env test

Production Deployment

# Check what will be applied
db-migrate check --env production --verbose

# Apply migrations (with dry run first)
db-migrate up --env production --dry-run
db-migrate up --env production

# Apply minimal production seeds
db-migrate seed --env production

CI/CD Pipeline

#!/bin/bash
set -e

# Test environment
echo "Setting up test database..."
db-migrate db:create myapp_test --env test
db-migrate up --env test
db-migrate seed:static --env test

# Run tests
npm test

# Production deployment
if [ "$DEPLOY_ENV" = "production" ]; then
  echo "Deploying to production..."
  db-migrate up --env production
  echo "Production migration completed"
fi

Exit Codes

# Success
0  # Command completed successfully

# Error codes  
1  # General error (migration failed, config error, etc.)
2  # Invalid arguments or usage
3  # Database connection error
4  # Migration file error

Error Handling

# Check exit status
db-migrate up --env production
if [ $? -eq 0 ]; then
  echo "Migrations completed successfully"
else
  echo "Migrations failed with exit code $?"
  exit 1
fi

# Verbose error information
db-migrate up --env production --verbose 2>&1 | tee migration.log

Integration with Package Scripts

Add to package.json:

{
  "scripts": {
    "migrate:up": "db-migrate up",
    "migrate:down": "db-migrate down",
    "migrate:create": "db-migrate create",
    "migrate:reset": "db-migrate reset",
    "migrate:check": "db-migrate check",
    "seed:run": "db-migrate seed",
    "seed:undo": "db-migrate seed:down",
    "db:create": "db-migrate db:create",
    "db:drop": "db-migrate db:drop",
    "db:setup": "npm run db:create && npm run migrate:up && npm run seed:run"
  }
}

Usage:

npm run migrate:up
npm run migrate:create add-users-table
npm run db:setup

Types

# Command syntax patterns
db-migrate <command> [arguments] [options]
db-migrate up [migration-name] [options]
db-migrate down [options]  
db-migrate create <migration-name> [options]
db-migrate check [options]
db-migrate reset [options]
db-migrate sync <migration-name> [options]
db-migrate db:create <database-name> [options]
db-migrate db:drop <database-name> [options]
db-migrate seed [options]
db-migrate seed:down [options]
db-migrate seed:reset [options]
db-migrate transition [options]

docs

cli-interface.md

configuration-management.md

data-seeding.md

database-interface.md

database-operations.md

index.md

migration-management.md

tile.json