wheels db rollback
Rollback database migrations to a previous state.
Synopsis
wheels db rollback [--steps=<n>] [--target=<version>] [--force]
Description
The wheels db rollback
command reverses previously applied migrations by running their down
methods. You can rollback a specific number of migrations or to a specific version.
Options
--steps=
Number of migrations to rollback. Defaults to 1.
wheels db rollback --steps=3
--target=
Rollback to a specific migration version.
wheels db rollback --target=20231201120000
--force
Skip the confirmation prompt.
wheels db rollback --force
Examples
Basic Usage
Rollback the last migration:
wheels db rollback
Rollback Multiple Migrations
Rollback the last 3 migrations:
wheels db rollback --steps=3
Rollback to Specific Version
Rollback to a specific point in time:
wheels db rollback --target=20231201120000
Force Rollback
Skip confirmation:
wheels db rollback --steps=5 --force
How It Works
Identifies Migrations: Determines which migrations to rollback
Confirmation: Asks for confirmation (unless --force)
Executes Down Methods: Runs the
down()
method of each migration in reverse orderUpdates Version: Updates the database version tracking
Important Considerations
Data Loss Warning
Rollbacks can result in data loss if migrations:
Drop tables
Remove columns
Delete records
Always backup before rolling back:
wheels db dump --output=backup-before-rollback.sql
wheels db rollback --steps=3
Migration Requirements
For rollback to work, migrations must:
Have a properly implemented
down()
methodBe reversible (some operations can't be undone)
Example migration with down method:
component {
function up() {
addColumn(table="users", columnName="age", columnType="integer");
}
function down() {
removeColumn(table="users", columnName="age");
}
}
Common Scenarios
Development Corrections
Made a mistake in the last migration:
# Rollback
wheels db rollback
# Fix the migration file
# Edit: db/migrate/20231204180000_AddAgeToUsers.cfc
# Run it again
wheels dbmigrate latest
Feature Rollback
Remove a feature and its database changes:
# Rollback feature migrations
wheels db rollback --target=20231201120000
# Remove feature code
# Deploy
Testing Migrations
Test that migrations are reversible:
# Apply migration
wheels dbmigrate latest
# Test rollback
wheels db rollback
# Reapply
wheels dbmigrate latest
Troubleshooting
"No down method"
If you see this error:
The migration doesn't have a
down()
methodAdd the method to make it reversible
Or use
wheels db reset
if in development
"Cannot rollback"
Some operations can't be reversed:
Data deletions (unless backed up in migration)
Complex transformations
External system changes
Rollback Fails
If rollback fails partway:
Check error message for specific issue
Fix the migration's down method
Manually correct database if needed
Update migration tracking table
Best Practices
Always implement down methods in migrations
Test rollbacks in development before production
Backup before rollback in production
Document irreversible changes in migrations
Use transactions in complex rollbacks
Related Commands
wheels db status
- Check current migration statewheels dbmigrate down
- Similar single rollbackwheels db reset
- Full database resetwheels db dump
- Backup before rollback
Last updated
Was this helpful?