---

Title: Configuration Reference. Description: Complete reference for capysquash-cli configuration options.

CONFIGURATION REFERENCE

Comprehensive guide to configuring capysquash for your specific needs.

CONFIGURATION FILE

Capysquash uses capysquash.config.json for configuration.

Generate Default Config

bash capysquash init-config

Creates capysquash.config.json with all available options and documentation.

CONFIGURATION STRUCTURE


 "safety_level": "standard",
 "output": 
 "format": "organized",
 "preserve_comments": true,
 "add_consolidation_comments": true,
 "directory": "squashed"
 ,
 "rules": 
 "table_operations": 
 "consolidate_create_alter": true,
 "remove_drop_create_cycles": true,
 "preserve_data_operations": true
 ,
 "function_operations": 
 "remove_duplicate_definitions": true,
 "preserve_signature_changes": false
 ,
 "index_operations": 
 "consolidate_index_creation": true,
 "remove_redundant_indexes": false
 
 ,
 "performance": 
 "streaming_threshold_mb": 5,
 "parallel_processing": true,
 "show_progress": true,
 "memory_limit_mb": 256,
 "batch_size": 50,
 "worker_count": 0
 ,
 "validation": 
 "docker_approach": "TWO_DATABASES",
 "enable_extension_detection": true,
 "auto_install_extensions": true,
 "enable_sql_fixes": true,
 "custom_extensions": 
 ,
 "modern_features": 
 "enable_vector_support": true,
 "enable_generated_columns": true,
 "enable_merge_statements": true,
 "enable_multirange_types": true
 ,
 "third_party_integrations": 
 "supabase_integration": 
 "enabled": true,
 "enable_rls": true,
 "storage_integration": true,
 "auth_integration": true
 ,
 "clerk_integration": 
 "enabled": false,
 "jwt_version": "v2"
 
 ,
 "postgresql_features": 
 "target_version": "16",
 "enable_partitioning": true,
 "enable_inheritance": true

CONFIGURATION SECTIONS

Safety Level

Options: paranoid, conservative, standard, aggressive

Default: standard


 "safety_level": "standard"

See Safety Levels for detailed explanation.

Output Configuration


 "output": 
 // Organization format
 "format": "organized", // "organized" | "single_file" | "by_category"

 // Comment preservation.
 "Preserve_comments": true,.
 "Add_consolidation_comments": true,.

 // Output location.
 "Directory": "squashed",.

 // File naming.
 "File_prefix": "",.
 "File_suffix": "_squashed".





 **Options:**

 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `format` | string | `"organized"` | Output organization format |
 | `preserve_comments` | boolean | `true` | Keep original comments |
 | `add_consolidation_comments` | boolean | `true` | Add consolidation metadata |
 | `directory` | string | `"squashed"` | Output directory path |
 | `file_prefix` | string | `""` | Prefix for output files |
 | `file_suffix` | string | `"_squashed"` | Suffix for output files |

 ### Consolidation Rules

 #### Table Operations

    ```json


"rules": {
"table_operations": {
"consolidate_create_alter": true,
"remove_drop_create_cycles": true,
"preserve_data_operations": true,
"merge_column_additions": true,
"optimize_constraints": true






| Option | Default | Description |
| --------------------------- | ------- | -------------------------------- |
| `consolidate_create_alter` | `true` | Merge CREATE + ALTER sequences |
| `remove_drop_create_cycles` | `true` | Eliminate redundant DROP/CREATE |
| `preserve_data_operations` | `true` | Keep INSERT/UPDATE/DELETE intact |
| `merge_column_additions` | `true` | Combine column additions |
| `optimize_constraints` | `true` | Consolidate constraints |

#### Function Operations


```json

 "rules": 
 "function_operations": 
 "remove_duplicate_definitions": true,
 "preserve_signature_changes": false,
 "consolidate_similar_functions": false

Index Operations


 "rules": 
 "index_operations": 
 "consolidate_index_creation": true,
 "remove_redundant_indexes": false,
 "optimize_index_order": true

Performance Configuration


 "performance": 
 // Streaming mode
 "streaming_threshold_mb": 5,
 "memory_limit_mb": 256,
 "batch_size": 50,

 // Parallelization.
 "Parallel_processing": true,.
 "Worker_count": 0, // 0 = auto-detect.

 // Progress tracking.
 "Show_progress": true,.
 "Progress_update_interval_ms": 500.





 **Auto-Detection:**
 - `worker_count: 0` → Uses `runtime.NumCPU()`
 - `streaming_threshold_mb: 5` → Enables streaming above 5MB

 ### Validation Configuration

    ```json


"validation": {
// Docker validation approach

"docker_approach": "TWO_DATABASES", // "TWO_CONTAINERS" | "TWO_DATABASES" | "SCHEMA_DIFF"

// Extension handling

"enable_extension_detection": true,

"auto_install_extensions": true,

"custom_extensions": {
"vector": "pgvector/pgvector:latest",
"postgis": "postgis/postgis:latest"

},

// SQL fixes

"enable_sql_fixes": true,

"sql_fix_patterns": [
"unsafe_to_safe",
"modern_syntax"

]





**Docker Approaches:**

| Approach | Speed | Accuracy | Use Case |
| ---------------- | ------ | -------- | ----------- |
| `TWO_CONTAINERS` | Slow | Highest | Production |
| `TWO_DATABASES` | Medium | High | Standard |
| `SCHEMA_DIFF` | Fast | Good | Development |

### Modern PostgreSQL Features


```json

 "modern_features": 
 "enable_vector_support": true,
 "enable_generated_columns": true,
 "enable_merge_statements": true,
 "enable_multirange_types": true,
 "enable_json_subscripting": true

Third-Party Integrations

Supabase


 "third_party_integrations": 
 "supabase_integration": 
 "enabled": true,
 "enable_rls": true,
 "storage_integration": true,
 "auth_integration": true,
 "detect_supabase_auth_patterns": true

Clerk


 "third_party_integrations": 
 "clerk_integration": 
 "enabled": true,
 "jwt_version": "v2",
 "detect_organization_patterns": true

PostgreSQL Version Targeting


 "postgresql_features": 
 "target_version": "16",
 "enable_partitioning": true,
 "enable_inheritance": true,
 "strict_version_compliance": false

ENVIRONMENT VARIABLES

Override configuration via environment variables:


# Safety level

export capysquash_SAFETY_LEVEL="conservative"

# Output directory

export capysquash_OUTPUT_DIR="clean_migrations"

# Performance

export capysquash_WORKER_COUNT=8
export capysquash_MEMORY_LIMIT=512

# AI providers

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."


 ## COMMAND-LINE OVERRIDES

 Command-line flags override config file:

    ```bash

# Override safety level

capysquash squash migrations/\*.sql --safety=aggressive

# Override output

capysquash squash migrations/\*.sql --output=custom/

# Override workers

capysquash squash migrations/\*.sql --workers=16



## CONFIGURATION EXAMPLES

### Development Configuration


```json

 "safety_level": "aggressive",
 "output": 
 "format": "single_file",
 "directory": "dev_clean"
 ,
 "rules": 
 "table_operations": 
 "consolidate_create_alter": true,
 "remove_drop_create_cycles": true
 
 ,
 "performance": 
 "streaming_threshold_mb": 10,
 "parallel_processing": true,
 "show_progress": true
 ,
 "validation": 
 "docker_approach": "SCHEMA_DIFF",
 "enable_sql_fixes": true

Production Configuration


 "safety_level": "conservative",
 "output": 
 "format": "organized",
 "preserve_comments": true,
 "add_consolidation_comments": true,
 "directory": "production_migrations"
 ,
 "rules": 
 "table_operations": 
 "consolidate_create_alter": true,
 "remove_drop_create_cycles": false,
 "preserve_data_operations": true
 ,
 "function_operations": 
 "remove_duplicate_definitions": false
 
 ,
 "performance": 
 "streaming_threshold_mb": 5,
 "parallel_processing": false,
 "show_progress": true
 ,
 "validation": 
 "docker_approach": "TWO_CONTAINERS",
 "enable_extension_detection": true,
 "auto_install_extensions": true

CI/CD Configuration


 "safety_level": "standard",
 "output": 
 "format": "organized",
 "directory": "squashed"
 ,
 "performance": 
 "streaming_threshold_mb": 5,
 "parallel_processing": true,
 "show_progress": false
 ,
 "validation": 
 "docker_approach": "TWO_DATABASES",
 "enable_extension_detection": true

CONFIGURATION PRECEDENCE

Configuration is loaded in this order (later overrides earlier):

Default embedded configuration
Config file (capysquash.config.json)
Environment variables
Command-line flags

TROUBLESHOOTING

Config Not Loading


# Verify config file exists

cat capysquash.config.json

# Check JSON syntax

jq . capysquash.config.json

# Use explicit path

capysquash squash migrations/\*.sql --config=./custom.config.json


 ### Invalid Configuration

    ```bash

# Validate config

capysquash init-config --validate

# Reset to defaults

capysquash init-config --force



## NEXT STEPS

- [Safety Levels](/docs/core-concepts/safety-levels) - Understand safety options
- [capysquash-engine Commands](/docs/capysquash-engine/commands) - Learn command usage
- [Troubleshooting](/docs/troubleshooting) - Common issues

---

On this page