---

Title: 'Getting Started with capysquash-cli' Description: '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

Navigate to Your Project

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

Validate Results (Optional but Recommended)

Ensure perfect schema equivalence:

capysquash validate migrations/ clean/

Docker validation process:

Spins up PostgreSQL container
Applies original migrations → exports schema
Applies optimized migrations → exports schema
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

### Option 1: Fresh Environments (Recommended)

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

```bash

# 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:17",
  - "cleanup": true
- },
- "patterns": {
  - "exclude": ["*seed*", "*data*"]
- }
}.

Then run with config:

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

Full configuration guide →

Next Steps

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

Documentation: Browse all CLI docs Community: GitHub Discussions Issues: Report bugs Email: support@capysquash.dev

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

---

On this page