Skip to content

SKILL.md

Latest commit

 

History

History
210 lines (161 loc) · 5.27 KB

SKILL.md

File metadata and controls

210 lines (161 loc) · 5.27 KB
name commandbox-migrations
description Use this skill when running database migrations from the CommandBox CLI using commandbox-migrations, including migrate up/down/reset/refresh, creating migration files, running seeders, and checking migration status. Covers CI/CD usage, configuration, and all CLI commands for cfmigrations.
applyTo **/*.{bx,cfc,cfm,bxm,json}

CommandBox Migrations Skill

When to Use This Skill

Load this skill when:

  • Running migrate up/down/reset/refresh from the CLI
  • Creating new migration files via migrate create
  • Running database seeders with migrate seed
  • Checking migration status with migrate status
  • Setting up CI/CD pipelines with database migrations
  • Configuring migration connection settings in box.json or .cfmigrations

Note: For the CFC-level Schema Builder and migration writing API, see the cfmigrations skill.

Installation

box install commandbox-migrations

Configuration

Option 1 — .cfmigrations file (recommended)

{
    "default": {
        "driver": "MSSQL",
        "host": "${DB_HOST}",
        "port": "${DB_PORT:1433}",
        "database": "${DB_DATABASE}",
        "username": "${DB_USERNAME}",
        "password": "${DB_PASSWORD}",
        "migrationsTable": "cfmigrations",
        "migrationsDirectory": "resources/database/migrations"
    }
}

Supported drivers: MSSQL, MySQL, PostgreSQL, SQLite, Generic

Option 2 — box.json settings

{
    "cfmigrations": {
        "connectionInfo": {
            "driver": "MySQL",
            "host": "${DB_HOST}",
            "port": "3306",
            "database": "${DB_DATABASE}",
            "username": "${DB_USERNAME}",
            "password": "${DB_PASSWORD}"
        },
        "migrationsTable": "cfmigrations",
        "migrationsDirectory": "resources/database/migrations"
    }
}

CLI Commands

Install Migration Table

# Create the cfmigrations tracking table (run once)
box migrate install

Create a Migration

# Create a new up/down migration file
box migrate create create_users_table

# Creates: resources/database/migrations/YYYY_MM_DD_HHMMSS_create_users_table.cfc

Run Migrations

# Run all pending migrations
box migrate up

# Run a specific number of migrations
box migrate up count=1

# Run a single named migration
box migrate up migration=create_users_table

# Rollback the last migration
box migrate down

# Rollback a specific number of steps
box migrate down count=3

# Rollback all migrations
box migrate reset

# Rollback then re-run all migrations (destructive!)
box migrate refresh

# Rollback then re-run with seeders
box migrate refresh --seed

Check Status

# Show which migrations have been run
box migrate status

Output example:

+----------------------------------------------------------------------+
| Migration                                         | Ran    | Order   |
+----------------------------------------------------|--------|---------|
| 2024_01_15_120000_create_users_table              | YES    | 1       |
| 2024_01_16_090000_create_posts_table              | YES    | 2       |
| 2024_02_01_143000_add_avatar_to_users             | NO     | -       |
+----------------------------------------------------------------------+

Seeders

# Run all seeders
box migrate seed

# Run a specific seeder
box migrate seed seedFile=UserSeeder

Using a Named Configuration

# Use a specific connection from .cfmigrations
box migrate up --configuraton=reporting

Production Patterns

CI/CD Pipeline (GitHub Actions)

- name: Run Migrations
  run: |
    box migrate up
  env:
    DB_HOST: localhost
    DB_DATABASE: myapp
    DB_USERNAME: ${{ secrets.DB_USER }}
    DB_PASSWORD: ${{ secrets.DB_PASS }}

CommandBox Task Runner

// tasks/MigrationTask.bx
class {

    function fresh( args = {} ) {
        print.yellowLine( "Refreshing database..." )
        command( "migrate refresh" ).params( seed: true ).run()
        print.greenLine( "Done!" )
    }

    function ci( args = {} ) {
        print.line( "Running CI migrations..." )
        command( "migrate install" ).run()
        command( "migrate up" ).run()
    }
}

Safe Production Deployment

# Only run pending - never rollback automatically in production
box migrate up

# Verify after deployment
box migrate status

Best Practices

  • Never run migrate reset or migrate refresh in production — these are destructive. Use only migrate up
  • Use environment variables for all connection credentials — never hardcode in box.json
  • Run migrate install once during initial server setup — idempotent, safe to run multiple times
  • Run migrate status before and after deployments to confirm state
  • Pin the box.json dependency version — ensures consistent CLI behavior across environments
  • Use named configurations (.cfmigrations) when multiple databases are needed (app vs. reporting)
  • Create seeders separately from migrations — seeders are for dev data, not schema state

Documentation