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

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

Example Output

+-----------------------------------------+-----------------------------------------+
| Datasource:                       myApp | Total Migrations:                     4 |
| Database Type:                       H2 | Available Migrations:                 0 |
|                                         | Current Version:         20250812161449 |
|                                         | Latest Version:          20250812161449 |
+-----------------------------------------+-----------------------------------------+
+----------+------------------------------------------------------------------------+
| migrated | 20250812161449_cli__create_reporting_procedures                        |
| migrated | 20250812161302_cli__example_1                                          |
| migrated | 20250812161250_cli__example_2                                          |
| migrated | 20250812154338_cli__example_3                                          |
+----------+------------------------------------------------------------------------+

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

1. Test migrations locally first

   # Test on development database
   wheels dbmigrate latest
   
   # Verify
   wheels dbmigrate info
   

2. Backup before production migrations

   # Backup database
   mysqldump myapp_production > backup.sql
   
   # Run migrations
   wheels dbmigrate latest
   

3. Use transactions

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

4. 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:

# .github/workflows/deploy.yml
- name: Run migrations
  run: |
    wheels dbmigrate latest
    wheels test app

Rollback Strategy

If issues occur after migration:

1. Use down migrations

   wheels dbmigrate down
   wheels dbmigrate down
   

2. Restore from backup

   mysql myapp_production < backup.sql
   

3. 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");
    }
}

See Also

• wheels dbmigrate info - Check migration status
• wheels dbmigrate up - Run single migration
• wheels dbmigrate down - Rollback migration
• wheels dbmigrate create blank - Create migration