rollback Command¶

Revert applied migrations to a previous state.

Description¶

The rollback command undoes migrations that have been applied to the database, reverting schema changes.

Usage¶

dbwarden rollback [OPTIONS]

Options¶

Short	Long	Description
`-d`	`--database NAME`	Target specific database
	`--all`	Rollback all configured databases
`-c`	`--count COUNT`	Number of migrations to rollback
`-t`	`--to-version VERSION`	Rollback to a specific version
`-v`	`--verbose`	Enable verbose logging

None of these options are required. All are optional.

Examples¶

Rollback Last Migration¶

dbwarden rollback

Rollback Multiple Migrations¶

# Rollback last 3 migrations
dbwarden rollback --count 3
# or
dbwarden rollback -c 3

Rollback to Specific Version¶

dbwarden rollback --to-version 0001
# or
dbwarden rollback -t 0001

Combined Options¶

dbwarden rollback -c 1 -t 0001 -v

Multi-Database Options¶

Rollback Specific Database¶

Use -d or --database to target a specific database:

# Rollback last migration on analytics database
dbwarden rollback -d analytics

# Rollback to specific version on analytics
dbwarden rollback -d analytics --to-version 0001 --verbose

Rollback All Databases¶

Use --all to rollback migrations on all configured databases:

# Rollback last migration on all databases
dbwarden rollback --all

# Rollback to specific version on all databases
dbwarden rollback --all --to-version 0001 --verbose

Example output with --all:

[INFO] Database: primary (sqlite)
[INFO] Nothing to rollback on primary.

[INFO] Database: analytics (postgresql)
Rolling back migration: 0003_create_reports.sql (version: 0003)
[ROLLED_BACK] 0003_create_reports.sql in 0.05s

[INFO] Database: legacy (mysql)
[INFO] Nothing to rollback on legacy.

Rollback completed successfully across all databases.

How It Works¶

Finds applied migrations: Identifies the most recent applied migrations
Acquires lock: Prevents concurrent migration operations
Parses rollback statements: Extracts SQL from -- rollback section
Executes rollback SQL: Reverts the schema changes
Records rollback: Removes migration record from tracking table

Internal Process¶

┌─────────────────────────────────────────────────────────┐
│  1. Acquire migration lock                              │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  2. Get last applied migration(s)                       │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  3. Parse rollback statements from migration file        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  4. Execute rollback SQL statements                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  5. Remove migration record from database                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  6. Release lock                                        │
└─────────────────────────────────────────────────────────┘

Understanding Rollback Behavior¶

With --count¶

dbwarden rollback --count 2

Rolls back the last 2 migrations in reverse order.

With --to-version¶

dbwarden rollback --to-version 0001

Rolls back all migrations after and including the specified version, leaving the database at the state just before that version.

Default Behavior¶

Without options, rolls back exactly 1 migration.

Output Examples¶

Successful Rollback¶

Rolling back migration: 0003_create_posts.sql (version: 0003)
Rollback completed: 0003_create_posts.sql in 0.03s
Rollback completed successfully: 1 migrations reverted.

Verbose Output¶

Rolling back migration: 0003_create_posts.sql (version: 0003)
DROP TABLE posts;
Rollback completed: 0003_create_posts.sql in 0.03s
Rollback completed successfully: 1 migrations reverted.

Nothing to Rollback¶

Nothing to rollback.

This occurs when: - No migrations have been applied - Database is at initial state

Rollback Considerations¶

Data Loss Warning¶

Rollback operations can result in data loss:

-- Example: Rollback drops tables
-- rollback
DROP TABLE posts;

-- Data in posts table WILL be lost!

Irreversible Operations¶

Some operations cannot be rolled back:

DROP TABLE: Data is deleted
TRUNCATE: Data is deleted
ALTER TABLE (some cases): Changes cannot be undone

Safe Rollbacks¶

Operations that can be safely rolled back:

CREATE INDEX: Just drop the index
ALTER TABLE ADD COLUMN: Drop the column
CREATE TABLE: Drop the table

Best Practices¶

1. Always Have a Backup¶

# Before rollback in production
pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql

2. Test Rollbacks¶

# Test on staging first
dbwarden rollback --to-version X
# Verify application still works
# If issues, re-apply:
dbwarden migrate --to-version X

3. Document Rollbacks¶

Note which migrations were rolled back and why:

# Document in commit or ticket
git commit -m "Rollback posts table - bug in post creation"

4. Use Version Control¶

Always have migrations committed before rolling back:

git add migrations/
git commit -m "Apply migrations"
# ... issues found ...
git log --oneline -n 5

Rollback Scenarios¶

Scenario 1: Bug in Migration¶

# Bug discovered after migration applied
dbwarden history
# 0003_create_posts.sql - has bug

# Rollback the buggy migration
dbwarden rollback --to-version 0003

# Fix the migration file
# Re-apply
dbwarden migrate

Scenario 2: Wrong Version Applied¶

# Wrong migration applied
dbwarden status
# Shows: 0003_create_posts applied (should be 0002)

# Rollback to correct version
dbwarden rollback --to-version 0002
# Correct migrations now at 0002

Scenario 3: Complete Reset¶

# Rollback all migrations
dbwarden rollback --count 999
# All migrations reverted to clean state

Troubleshooting¶

"Nothing to rollback"¶

Check if migrations were applied:

dbwarden history
dbwarden status

Rollback Fails¶

Check migration file has -- rollback section
Verify rollback SQL is correct
Run with --verbose for details

Lock Held¶

dbwarden lock-status
# If locked, wait or:
dbwarden unlock

Rollback and Migrate Together¶

You can rollback and reapply in one operation:

# Rollback and reapply
dbwarden rollback --to-version X
# Fix migration files
dbwarden migrate --to-version X

CI/CD Rollback¶

GitHub Actions Rollback¶

name: Emergency Rollback

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Rollback
        run: dbwarden rollback --to-version ${{ github.event.inputs.version }}
        env:
          DBWARDEN_SQLALCHEMY_URL: ${{ secrets.DATABASE_URL }}