CONFIGURATION REFERENCE

Comprehensive guide to configuring capysquash for your specific needs.

CONFIGURATION FILE

capysquash uses capysquash.config.json for configuration.

Generate Default Config

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

{
  "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

{
  "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

{
  "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

{
  "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:

# 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

{
  "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

# Validate config
capysquash init-config --validate

# Reset to defaults
capysquash init-config --force

NEXT STEPS

Safety Levels - Understand safety options
capysquash-engine Commands - Learn command usage
Troubleshooting - Common issues

Configuration Reference