Skip to content

squash Command

Merge multiple consecutive migrations into a single migration.

Description

The squash command combines multiple applied migrations into one migration file, simplifying migration history.

Usage

dbwarden squash

Options

Option Description
--verbose, -v Enable verbose logging

Examples

Basic Usage

dbwarden squash

What It Does

  1. Collects applied migrations: Gathers all applied migration files
  2. Combines upgrade SQL: Merges all -- upgrade sections
  3. Combines rollback SQL: Merges all -- rollback sections
  4. Creates new migration: Generates a consolidated migration file
  5. Updates tracking: Records new migration in database

Before Squashing

Migrations:
├── 0001_create_users.sql
├── 0002_add_username.sql
├── 0003_add_email.sql
└── 0004_add_password.sql

After Squashing

Migrations:
└── 0001_initial_schema.sql

Use Cases

Cleanup Migration History

Reduce number of migration files:

  • Many small migrations → fewer large ones
  • Easier to review
  • Faster migration execution

Performance Optimization

Fewer migrations = fewer files to parse and execute.

Requirements

  1. All migrations applied: No pending migrations
  2. No concurrent processes: Database not in active use
  3. Backup recommended: Before squashing in production

Important Considerations

Downtime

Squashing requires exclusive database access: - Lock is acquired - All migrations are reapplied - Can cause downtime in production

Testing Required

Always test squashing: 1. On development database 2. On staging environment 3. Before production

Rollback Changes

After squashing: - Old migration files are removed - New consolidated migration replaces them - Cannot easily rollback to old state

Best Practices

When to Squash

  • After many small migrations (10+)
  • Before major releases
  • During maintenance windows
  • Never in production during peak hours

When NOT to Squash

  • During active development
  • Before code freeze
  • If migrations are frequently changing
  • In production without testing

Backup First

# Backup database
pg_dump $DATABASE_URL > backup_before_squash.sql

# Backup migrations
cp -r migrations migrations_backup

Troubleshooting

Pending Migrations Exist

Cannot squash: 5 migrations are pending.
Please run 'dbwarden migrate' first.

Apply all migrations before squashing.

Migration Table Doesn't Exist

No migrations found. Nothing to squash.

Apply at least one migration.

Alternative: Manual Squashing

For more control, manually combine migrations:

# 1. Create new migration
dbwarden new "consolidate user migrations"

# 2. Edit the file, combining SQL from:
# - 0001_create_users.sql
# - 0002_add_username.sql
# - 0003_add_email.sql

See Also