CAPYSQUASH

Getting Started with capysquash-cli

Get your first migration optimization running in under 5 minutes with the CLI

Getting Started with capysquash-cli

Optimize your PostgreSQL migrations from the command line in under 5 minutes

capysquash-cli is a free, open-source tool that consolidates messy migration files into clean, organized SQL. Perfect for local development and CI/CD pipelines.

Prefer a visual interface? Check out CAPYSQUASH Platform for one-click optimization with team collaboration features.

Prerequisites

Before you begin:

☑ capysquash-cli installed

See Installation Guide

☑ Docker running (optional)

Required for validation

☑ PostgreSQL migrations

Supabase, Neon, or any framework

☑ Terminal access

Bash, Zsh, or PowerShell

Your First Optimization

Open your terminal and go to your project directory:

cd your-project

Typical project structures:

# Supabase
your-project/supabase/migrations/

# Prisma
your-project/prisma/migrations/

# Custom
your-project/migrations/

Analyze Your Migrations

See what can be optimized:

capysquash analyze migrations/

Example output:

🔍 Analyzing migrations...

Found: 287 migration files
Total size: 2.1 MB
Estimated optimization: 95.8% reduction (287 → 12 files)

Safe to consolidate:
  ✓ 45 CREATE TABLE statements
  ✓ 123 ALTER TABLE statements
  ✓ 67 CREATE INDEX statements
  ✓ 28 RLS policies

Recommendation: Run with --safety=standard

What this means: capysquash found 287 files that can be safely consolidated into just 12 files!

Run the Optimization

Generate your optimized migrations:

capysquash squash migrations/*.sql \
  --output clean/ \
  --safety standard

What happens:

  • Parses all migrations using PostgreSQL's actual parser
  • Analyzes dependencies between operations
  • Consolidates safe operations
  • Generates clean, organized output files

You'll see:

⚡ Optimizing migrations...
✓ Parsed 287 files
✓ Resolved dependencies
✓ Consolidated operations
✓ Generated 12 clean files

Output: clean/

Next: Run 'capysquash validate migrations/ clean/' to verify

Ensure perfect schema equivalence:

capysquash validate migrations/ clean/

Docker validation process:

  1. Spins up PostgreSQL container
  2. Applies original migrations → exports schema
  3. Applies optimized migrations → exports schema
  4. Compares both schemas byte-by-byte

Success output:

🐳 Docker validation starting...
✓ Original schema: 42 tables, 187 columns, 23 indexes
✓ Optimized schema: 42 tables, 187 columns, 23 indexes
✓ PERFECT MATCH - Schemas are identical

Safe to deploy! ✨

Zero risk: If schemas don't match perfectly, capysquash will not generate the optimized files.

Review Your Clean Migrations

Check the clean/ directory:

Before (287 files):

migrations/
├── 001_create_users.sql
├── 002_add_email.sql
├── 003_add_email_index.sql
├── 004_add_password.sql
...
└── 287_latest_change.sql

After (12 files):

clean/
├── 001_create_users_complete.sql (merged 1-45)
├── 002_create_posts.sql (merged 46-89)
├── 003_create_comments.sql (merged 90-124)
├── 004_add_indexes.sql (merged 125-187)
...
└── 012_latest_changes.sql (merged 250-287)

🎉 YOU DID IT!

Your migrations are now clean, organized, and validated. Ready to deploy!

What to Do with Optimized Migrations

Use optimized migrations for new development, staging, or test environments:

# For a fresh database
psql $DATABASE_URL -f clean/001_create_users_complete.sql
psql $DATABASE_URL -f clean/002_create_posts.sql
# ... etc

Perfect for:

  • New team member onboarding
  • Staging environment resets
  • Test database setup
  • Disaster recovery

Option 2: Replace Existing (Advanced)

Replace your migration history (requires team coordination):

# 1. BACKUP FIRST
cp -r migrations migrations.backup

# 2. Create feature branch
git checkout -b optimize-migrations

# 3. Replace migrations
rm migrations/*.sql
cp clean/*.sql migrations/

# 4. Update migration tracker (if using a framework)
# For Prisma: update _prisma_migrations table
# For Django: update django_migrations table
# For Rails: update schema_migrations table

# 5. Test thoroughly in development
# 6. Review with team
# 7. Merge carefully

Team coordination required! Make sure everyone on the team is aware of the migration history replacement.

Understanding Safety Levels

capysquash offers 4 safety levels:

Recommended for most use cases

  • Consolidates safe operations
  • Preserves critical separations
  • Balanced optimization (~85-95% reduction)
  • Production-ready with validation
capysquash squash migrations/*.sql --safety standard

For production databases (first time)

  • Very cautious consolidation
  • Preserves more separation
  • Moderate optimization (~60-75% reduction)
  • Extra safety margin
capysquash squash migrations/*.sql --safety conservative

For development and testing

  • Maximum consolidation
  • Fewer files, larger batches
  • High optimization (~95-98% reduction)
  • Best for fresh environments
capysquash squash migrations/*.sql --safety aggressive

Maximum safety, minimal changes

  • Only obvious consolidations
  • Preserves most structure
  • Lower optimization (~40-60% reduction)
  • Zero-risk approach
capysquash squash migrations/*.sql --safety paranoid

Learn more about safety levels →

Common Workflows

Local Development

# Quick analysis during development
capysquash analyze migrations/

# Optimize for local testing
capysquash squash migrations/*.sql \
  --output dev-clean/ \
  --safety aggressive

CI/CD Integration

# GitHub Actions example
- name: Optimize Migrations
  run: |
    capysquash squash migrations/*.sql \
      --output optimized/ \
      --safety standard
    capysquash validate migrations/ optimized/

Full CI/CD guide →

Team Collaboration

# 1. Developer A adds migrations
git add migrations/123_new_feature.sql
git commit -m "Add feature migrations"

# 2. Before merge, optimize for review
capysquash analyze migrations/

# 3. Team reviews optimized version
capysquash squash migrations/*.sql --output review/ --dry-run

# 4. Decide: Keep original or use optimized for fresh envs

Configuration (Optional)

Create a config file for consistent settings:

capysquash.config.json
{
  "safetyLevel": "standard",
  "outputDir": "clean",
  "autoValidate": true,
  "docker": {
    "image": "postgres:16-ubuntu",
    "cleanup": true
  },
  "patterns": {
    "exclude": ["*seed*", "*data*"]
  }
}

Then run with config:

capysquash squash migrations/*.sql --config capysquash.config.json

Full configuration guide →

Next Steps

Command Reference

Learn all capysquash-cli commands and options

TUI Mode

Use the interactive terminal interface

Examples

Real-world usage examples and patterns

Advanced Usage

Flags, options, and advanced configurations

Troubleshooting

"command not found"

# Ensure Go bin is in PATH
export PATH=$PATH:$(go env GOPATH)/bin

# Or reinstall
brew install capysquash/tap/capysquash-cli

Docker validation fails

# Ensure Docker is running
docker ps

# Or skip validation
capysquash squash migrations/*.sql --output clean/ --no-validate

Optimization seems too aggressive

# Use more conservative safety level
capysquash squash migrations/*.sql --safety conservative

# Or paranoid for maximum safety
capysquash squash migrations/*.sql --safety paranoid

Full troubleshooting guide →

Getting Help

Ready for more? Explore command reference or try the TUI mode!

How is this guide?

On this page

Getting Started with capysquash-cliPrerequisitesYour First OptimizationNavigate to Your ProjectAnalyze Your MigrationsRun the OptimizationValidate Results (Optional but Recommended)Review Your Clean MigrationsWhat to Do with Optimized MigrationsOption 1: Fresh Environments (Recommended)Option 2: Replace Existing (Advanced)Understanding Safety LevelsCommon WorkflowsLocal DevelopmentCI/CD IntegrationTeam CollaborationConfiguration (Optional)Next StepsTroubleshooting"command not found"Docker validation failsOptimization seems too aggressiveGetting Help