Configuration reference for pgsquash-engine when using capysquash-cli or the library API

ENGINE CONFIGURATION

Configure pgsquash-engine behavior when using capysquash-cli or the library API with pgsquash.config.json.

💡 Using CAPYSQUASH Platform? Configuration is handled through the web interface. This guide is for capysquash-cli and library API users.

CONFIGURATION FILE

Location

pgsquash searches for configuration in this order:

Path specified with --config flag
./pgsquash.config.json in current directory
Default embedded configuration

Generate Configuration

# Generate default config
capysquash init-config

# Generate at custom path
capysquash init-config --config custom.json

# Force overwrite existing
capysquash init-config --force

BASIC CONFIGURATION

Minimal Example

{
  "safety_level": "standard",
  "output": {
    "directory": "squashed",
    "format": "sql"
  }
}

Complete Example

{
  "safety_level": "standard",
  "prod_db_dsn": "",
  "output": {
    "directory": "squashed",
    "format": "sql",
    "preserve_timestamps": false,
    "single_file": false
  },
  "rules": {
    "consolidate_creates": true,
    "consolidate_alters": true,
    "remove_drop_create_cycles": true,
    "consolidate_rls": true,
    "deduplicate_functions": false
  },
  "exclude_patterns": ["auth.*", "extensions.*"],
  "include_schemas": ["public"],
  "performance": {
    "streaming": false,
    "parallel_processing": true,
    "workers": 0,
    "batch_size": 50,
    "memory_limit_mb": 256
  }
}

TOP-LEVEL SETTINGS

safety_level

Type: string Default: "standard" Options: "paranoid", "conservative", "standard", "aggressive"

Controls optimization level.

{
  "safety_level": "conservative"
}

Learn about safety levels →

prod_db_dsn

Type: string Default: From PROD_DB_DSN environment variable

Database connection string for paranoid mode.

{
  "prod_db_dsn": "postgres://user:password@localhost:5432/database"
}

When needed:

Required for paranoid safety level
Required for --backup flag
Used for dead code analysis

Security tip: Use environment variable instead:

export PROD_DB_DSN="postgres://user:pass@localhost/db"

exclude_patterns

Type: array of strings Default: ["auth.*", "extensions.*"]

Patterns for objects to exclude from consolidation.

{
  "exclude_patterns": [
    "auth.*",
    "extensions.*",
    "temp_*",
    "test_*"
  ]
}

Pattern syntax:

* - Wildcard
auth.* - Matches auth. prefix
*.temp - Matches .temp suffix

include_schemas

Type: array of strings Default: ["public"]

Schemas to include in processing.

{
  "include_schemas": ["public", "app", "reporting"]
}

Options:

["*"] - All schemas
["public"] - Public only (default)
["public", "app"] - Specific schemas

OUTPUT CONFIGURATION

format

Type: string Default: "sql" Options: "sql", "json", "yaml"

Output file format.

{
  "output": {
    "format": "sql"
  }
}

preserve_timestamps

Type: boolean Default: false

Keep original migration timestamps in filenames.

{
  "output": {
    "preserve_timestamps": true
  }
}

Example:

false: 0001_initial.sql, 0002_add_users.sql
true: 20240101_120000_initial.sql

single_file

Type: boolean Default: false

Consolidate all migrations into a single file.

{
  "output": {
    "single_file": true,
    "directory": "squashed",
    "filename": "schema.sql"
  }
}

RULES CONFIGURATION

Control which optimization rules are applied.

consolidate_creates

Type: boolean Default: true

Consolidate CREATE TABLE + ALTER TABLE into single CREATE.

{
  "rules": {
    "consolidate_creates": true
  }
}

Example:

-- Before
CREATE TABLE users (id INT);
ALTER TABLE users ADD email VARCHAR(255);

-- After
CREATE TABLE users (
  id INT,
  email VARCHAR(255)
);

consolidate_alters

Type: boolean Default: true

Merge multiple ALTER statements.

{
  "rules": {
    "consolidate_alters": true
  }
}

remove_drop_create_cycles

Type: boolean Default: true (standard+) Safety: Not available in paranoid/conservative

Remove unnecessary DROP/CREATE cycles.

{
  "rules": {
    "remove_drop_create_cycles": true
  }
}

consolidate_rls

Type: boolean Default: true (standard+)

Consolidate Row Level Security policies.

{
  "rules": {
    "consolidate_rls": true
  }
}

deduplicate_functions

Type: boolean Default: false (aggressive only)

Remove duplicate function definitions.

{
  "rules": {
    "deduplicate_functions": true
  }
}

PERFORMANCE SETTINGS

streaming

Type: boolean Default: false

Enable streaming mode for large migration sets (500+ files).

{
  "performance": {
    "streaming": true
  }
}

parallel_processing

Type: boolean Default: true

Enable parallel processing of migrations.

{
  "performance": {
    "parallel_processing": true
  }
}

workers

Type: integer Default: 0 (auto-detect based on CPU cores)

Number of worker threads.

{
  "performance": {
    "workers": 4
  }
}

Recommendations:

0 - Auto-detect (recommended)
1-2 - Low memory systems
4-8 - Standard workstations
8-16 - High-performance servers

batch_size

Type: integer Default: 50

Number of migrations to process per batch.

{
  "performance": {
    "batch_size": 100
  }
}

memory_limit_mb

Type: integer Default: 256

Memory limit in megabytes.

{
  "performance": {
    "memory_limit_mb": 512
  }
}

ENVIRONMENT VARIABLES

Override config with environment variables:

Variable	Config Key	Example
`PROD_DB_DSN`	`prod_db_dsn`	`postgres://...`
`ANTHROPIC_API_KEY`	AI features	`sk-ant-...`
`OPENAI_API_KEY`	AI features	`sk-...`
`PGSQUASH_SAFETY`	`safety_level`	`conservative`

export PROD_DB_DSN="postgres://user:pass@localhost/db"
export ANTHROPIC_API_KEY="sk-ant-..."
capysquash squash migrations/*.sql

COMMON CONFIGURATIONS

Development (Fast)

{
  "safety_level": "aggressive",
  "output": {
    "directory": "dev-clean"
  },
  "performance": {
    "streaming": false,
    "parallel_processing": true
  }
}

Staging (Balanced)

{
  "safety_level": "standard",
  "output": {
    "directory": "squashed"
  },
  "performance": {
    "streaming": false,
    "parallel_processing": true
  }
}

Production (Safe)

{
  "safety_level": "conservative",
  "prod_db_dsn": "${PROD_DB_DSN}",
  "output": {
    "directory": "production-clean",
    "preserve_timestamps": true
  },
  "performance": {
    "streaming": false,
    "parallel_processing": false,
    "workers": 1
  }
}

Large Datasets (500+ migrations)

{
  "safety_level": "standard",
  "output": {
    "directory": "squashed"
  },
  "performance": {
    "streaming": true,
    "parallel_processing": true,
    "workers": 8,
    "batch_size": 100,
    "memory_limit_mb": 512
  }
}

PLATFORM-SPECIFIC CONFIGS

Supabase

{
  "safety_level": "standard",
  "output": {
    "directory": "supabase/migrations-clean"
  },
  "exclude_patterns": [
    "auth.*",
    "storage.*",
    "realtime.*"
  ],
  "include_schemas": ["public"]
}

Neon

{
  "safety_level": "standard",
  "output": {
    "directory": "neon/migrations-clean",
    "preserve_timestamps": true
  }
}

Prisma

{
  "safety_level": "conservative",
  "output": {
    "directory": "prisma/migrations-clean",
    "preserve_timestamps": true
  }
}

VALIDATION

Validate your configuration:

# Test configuration
capysquash analyze migrations/*.sql --config pgsquash.config.json --dry-run

NEXT STEPS

CAPYSQUASH Platform - Easiest way to get started
capysquash-cli Commands - CLI command reference
Safety Levels Guide - Understanding safety levels
TUI Guide - Interactive terminal interface

Engine Configuration

On this page