wheels dbmigrate create blank

Create an empty database migration file with up and down methods.

Synopsis

wheels dbmigrate create blank <name>

CommandBox Parameter Syntax

This command supports multiple parameter formats:

• Positional parameters: wheels dbmigrate create blank addIndexes (name as positional)

• Named parameters: name=value (e.g., name=addIndexes, description="Add indexes")

• Flag parameters: --flag=value (e.g., --name=addIndexes)

Parameter Mixing Rules:

✅ ALLOWED:

• Positional: wheels dbmigrate create blank addIndexes

• All named: name=addIndexes description="Custom migration"

• Positional + named: wheels dbmigrate create blank addIndexes description="Add indexes"

❌ NOT ALLOWED:

• Mixing positional + named for same parameter: wheels dbmigrate create blank addIndexes name=other

Recommendation: Use positional for name, named for optional parameters: wheels dbmigrate create blank addIndexes description="My migration"

Description

The dbmigrate create blank command generates a new empty migration file with the basic structure including up() and down() methods. This provides a starting point for custom migrations where you need full control over the migration logic.

Options

--name

• Type: String

• Required: Yes

• Description: The name of the migration (will be prefixed with timestamp)

--description

• Type: String

• Default: Empty

• Description: Add a description comment to the migration file

Examples

Create a basic empty migration

# Positional (recommended)
wheels dbmigrate create blank add_custom_indexes

# OR flag syntax
wheels dbmigrate create blank --name=add_custom_indexes

# OR named
wheels dbmigrate create blank name=add_custom_indexes

Create migration with description

# Positional + named (recommended)
wheels dbmigrate create blank update_user_permissions description="Add role-based permissions to users"

# OR all flags
wheels dbmigrate create blank --name=update_user_permissions --description="Add role-based permissions to users"

# OR all named
wheels dbmigrate create blank name=update_user_permissions description="Add role-based permissions to users"

Generated File Structure

The command creates a file named YYYYMMDDHHmmss_<name>.cfc with the following structure:

component extends="wheels.migrator.Migration" hint="<description>" {

    function up() {
        transaction {
            // Add your migration code here
        }
    }

    function down() {
        transaction {
            // Add code to reverse the migration
        }
    }

}

Use Cases

Custom Database Operations

For complex operations not covered by other generators:

# Create migration for custom stored procedure
wheels dbmigrate create blank --name=create_reporting_procedures

# Edit the file to add:
# - CREATE PROCEDURE statements
# - Complex SQL operations
# - Multiple related changes

Data Migrations

When you need to migrate data, not just schema:

# Create data migration
wheels dbmigrate create blank --name=normalize_user_emails

# Edit to add data transformation logic
# Example: lowercase all email addresses

Multi-Step Operations

For migrations requiring multiple coordinated changes:

# Create complex migration
wheels dbmigrate create blank --name=refactor_order_system

# Edit to include:
# - Create new tables
# - Migrate data
# - Drop old tables
# - Update foreign keys

Database-Specific Features

For database-specific features not abstracted by Wheels:

# Create migration for PostgreSQL-specific features
wheels dbmigrate create blank --name=add_json_columns

# Edit to use PostgreSQL JSON operations

Best Practices

1. Descriptive Names

Use clear, descriptive names that indicate the migration's purpose:

# Good
wheels dbmigrate create blank --name=add_user_authentication_tokens

# Bad
wheels dbmigrate create blank --name=update1

2. Implement Both Methods

Always implement both up() and down() methods:

function up() {
    transaction {
        execute("CREATE INDEX idx_users_email ON users(email)");
    }
}

function down() {
    transaction {
        execute("DROP INDEX idx_users_email");
    }
}

3. Use Transactions

Wrap operations in transactions for atomicity:

function up() {
    transaction {
        // All operations succeed or all fail
        createTable("new_table");
        execute("INSERT INTO new_table SELECT * FROM old_table");
        dropTable("old_table");
    }
}

4. Add Comments

Document complex operations:

function up() {
    transaction {
        // Create composite index for query optimization
        // This supports the findActiveUsersByRegion() query
        execute("
            CREATE INDEX idx_users_active_region 
            ON users(is_active, region_id) 
            WHERE is_active = 1
        ");
    }
}

Available Migration Methods

Within your blank migration, you can use these helper methods:

• createTable(name, options) - Create a new table

• dropTable(name) - Drop a table

• addColumn(table, column, type, options) - Add a column

• removeColumn(table, column) - Remove a column

• changeColumn(table, column, type, options) - Modify a column

• addIndex(table, columnNames, unique, indexName) - Add an index

• removeIndex(table, column) - Remove an index

• execute(sql) - Execute raw SQL

• announce(message) - Output a message during migration

Notes

• Migration files are created in /app/migrator/migrations/ or your configured migration path

• The timestamp ensures migrations run in the correct order

• Always test migrations in development before production

• Keep migrations focused on a single purpose

Related Commands

• wheels dbmigrate create table - Create a table migration

• wheels dbmigrate create column - Create a column migration

• wheels dbmigrate up - Run migrations

• wheels dbmigrate down - Rollback migrations

• wheels dbmigrate info - View migration status