wheels dbmigrate create blank

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

Synopsis

wheels dbmigrate create blank --name=<name> [options]

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)

--datasource

• Type: String

• Default: Application default

• Description: Specify the datasource this migration targets

--description

• Type: String

• Default: Empty

• Description: Add a description comment to the migration file

--template

• Type: String

• Default: blank

• Description: Use a custom template for the migration

Examples

Create a basic empty migration

wheels dbmigrate create blank --name=add_custom_indexes

Create migration with description

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

Create migration for specific datasource

wheels dbmigrate create blank --name=legacy_data_cleanup --datasource=legacyDB

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, column, options) - 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