Command Line Tools

wheels dbmigrate latest

Run all pending database migrations to bring database to latest version.

Synopsis

wheels dbmigrate latest

Alias: wheels db latest

Description

The wheels dbmigrate latest command runs all pending migrations in chronological order, updating your database schema to the latest version. This is the most commonly used migration command.

Parameters

None.

How It Works

Retrieves current database version and latest version
Executes dbmigrate exec with the latest version
Automatically runs dbmigrate info after completion
Updates version tracking after successful migration

Example Output

==================================================
    Updating Database Schema to Latest Version
==================================================

Latest Version:           20260123185445
==================================================
               Migration Execution
==================================================

Target Version:           20260123185445
--------------------------------------------------
Sending: http://0.0.0.0:8080/?controller=wheels&action=wheels&view=cli&command=migrateTo&version=20260123185445
[SUCCESS]: Call to bridge was successful.
[SUCCESS]: Migration completed successfully!

Sending: http://0.0.0.0:8080/?controller=wheels&action=wheels&view=cli&command=info
[SUCCESS]: Call to bridge was successful.
==================================================
            Database Migration Status
==================================================


Database Information
--------------------------------------------------
Datasource:               dbapp_test
Database Type:            MySQL

Migration Status
--------------------------------------------------
Total Migrations:         17
Available Migrations:     14
Current Version:          20260116163515
Latest Version:           20260123185445
--------------------------------------------------

Migration Files
--------------------------------------------------
╔══════════╤══════════════════════════════════════════════════════╗
║ STATUS   │ FILE                                                 ║
╠══════════╪══════════════════════════════════════════════════════╣
║          │ 20260123185445_cli_create_table_user                 ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260123183026_cli_remove_table_blog_posts           ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260123182948_create_blog_posts_table               ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260122173254_cli_create_table_user_roles           ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260119145114_cli_create_column_parts_feature       ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260119144642_cli_blank_students                    ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260119112924_cli_create_table_students             ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260119111943_cli_create_table_books                ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116170453_cli_create_table_users                ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116170311_cli_create_table_users                ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116165727_cli_create_column_user_required_field ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116164432_cli_create_column_product_price       ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116164211_cli_create_column_user_bio            ║
╟──────────┼──────────────────────────────────────────────────────╢
║          │ 20260116163907_cli_create_column_user_email          ║
╟──────────┼──────────────────────────────────────────────────────╢
║ migrated │ 20260116163515_cli_blank_create_reporting_procedures ║
╟──────────┼──────────────────────────────────────────────────────╢
║ migrated │ 20260116160315_cli_remove_table_resources            ║
╟──────────┼──────────────────────────────────────────────────────╢
║ migrated │ 20260116155320_cli_remove_table_users                ║
╚══════════╧══════════════════════════════════════════════════════╝

Migration Execution

Each migration file must contain:

component extends="wheels.migrator.Migration" {

    function up() {
        // Database changes go here
        transaction {
            // Use transaction for safety
        }
    }

    function down() {
        // Rollback logic (optional)
        transaction {
            // Reverse the up() changes
        }
    }

}

Transaction Safety

Migrations run within transactions:

All changes in a migration succeed or fail together
Database remains consistent
Failed migrations can be retried

Common Migration Operations

Create Table

function up() {
    transaction {
        t = createTable("products");
        t.string("name");
        t.decimal("price");
        t.timestamps();
        t.create();
    }
}

Add Column

function up() {
    transaction {
        addColumn(table="users", columnNames="email", type="string");
    }
}

Add Index

function up() {
    transaction {
        addIndex(table="users", columnNames="email", unique=true);
    }
}

Modify Column

function up() {
    transaction {
        changeColumn(table="products", columnNames="price", type="decimal", precision=10, scale=2);
    }
}

Best Practices

Test migrations locally first

# Test on development database
wheels dbmigrate latest

# Verify
wheels dbmigrate info

Backup before production migrations

# Backup database
mysqldump myapp_production > backup.sql

# Run migrations
wheels dbmigrate latest

Use transactions

function up() {
    transaction {
        // All changes here
    }
}

Make migrations reversible

function down() {
    transaction {
        dropTable("products");
    }
}

Environment-Specific Migrations

Migrations can check environment:

function up() {
    transaction {
        // Always run
        addColumn(table="users", column="lastLogin", type="datetime");

        // Development only
        if (get("environment") == "development") {
            // Add test data
            sql("INSERT INTO users (email) VALUES ('test@example.com')");
        }
    }
}

Checking Migrations

Preview migrations before running:

# Check what would run
wheels dbmigrate info

# Review migration files
ls app/migrator/migrations/

Performance Considerations

For large tables:

function up() {
    transaction {
        // Add index concurrently (if supported)
        if (get("databaseType") == "postgresql") {
            sql("CREATE INDEX CONCURRENTLY idx_users_email ON users(email)");
        } else {
            addIndex(table="users", columns="email");
        }
    }
}

Continuous Integration

Add to CI/CD pipeline:

- name: Run migrations
  run: |
    wheels dbmigrate latest
    wheels test app

Rollback Strategy

If issues occur after migration:

Use down migrations

wheels dbmigrate down
wheels dbmigrate down

Restore from backup
Terminal window
```
mysql myapp_production < backup.sql
```
Fix and retry
- Fix migration file
- Run wheels dbmigrate latest

Common Issues

Timeout on Large Tables

function up() {
    // Increase timeout for large operations
    setting requestTimeout="300";

    transaction {
        // Long running operation
    }
}

Foreign Key Constraints

function up() {
    transaction {
        // Disable checks temporarily
        sql("SET FOREIGN_KEY_CHECKS=0");

        // Make changes
        dropTable("orders");

        // Re-enable
        sql("SET FOREIGN_KEY_CHECKS=1");
    }
}

wheels dbmigrate latest

wheels dbmigrate latest

Synopsis

Description

Parameters

How It Works

Example Output

Migration Execution

Transaction Safety

Common Migration Operations

Create Table

Add Column

Add Index

Modify Column

Best Practices

Environment-Specific Migrations

Checking Migrations

Performance Considerations

Continuous Integration

Rollback Strategy

Common Issues

Timeout on Large Tables

Foreign Key Constraints

See Also