Migrating from PgBouncer

scry-proxy is a drop-in replacement for PgBouncer with enhanced observability, circuit breaker protection, and hybrid pooling.

Drop-In Replacement

scry-proxy can read your existing PgBouncer configuration directly, making migration as simple as pointing to your current config file:

# Use your existing pgbouncer.ini directly
./scry-proxy --pgbouncer-config /etc/pgbouncer/pgbouncer.ini

scry-proxy parses your pgbouncer.ini and automatically maps settings to its native configuration. This means you can test scry-proxy alongside PgBouncer without changing any configuration files.

Tip: Start by running scry-proxy on a different port while keeping PgBouncer running. This lets you validate behavior before switching traffic.

Configuration Mapping

The following table shows how PgBouncer settings map to scry-proxy equivalents:

PgBouncer Setting scry-proxy Equivalent Notes
listen_addr SCRY_LISTEN__HOST Address to bind the proxy
listen_port SCRY_LISTEN__PORT Port for client connections
pool_mode SCRY_POOL__MODE session, transaction, or statement
default_pool_size SCRY_POOL__SIZE Backend connections per pool
min_pool_size SCRY_POOL__MIN_SIZE Minimum idle connections
max_client_conn SCRY_POOL__MAX_CLIENTS Maximum client connections
server_idle_timeout SCRY_POOL__IDLE_TIMEOUT Close idle backend connections
server_connect_timeout SCRY_BACKEND__CONNECT_TIMEOUT Backend connection timeout
auth_file SCRY_AUTH__FILE User authentication file

For a complete list of configuration options, see the Configuration Reference.

What You Gain

Migrating from PgBouncer to scry-proxy gives you access to features designed for modern production environments:

Per-Query Observability

Prometheus metrics with query fingerprinting, latency histograms, and error tracking. See exactly which queries are slow or failing.

Circuit Breaker

Automatic protection against cascading failures. When backends become unhealthy, the circuit opens to prevent request pile-up.

Health Monitoring

Built-in health check endpoints for load balancers and Kubernetes. Configurable liveness and readiness probes.

Query Anonymization

Automatically redact sensitive values from query logs and metrics while preserving query structure for analysis.

Hybrid Pooling

Intelligent pool mode selection per connection. Mix session and transaction pooling based on application needs.

Modern Deployment

Single binary with no dependencies. Native support for containers, systemd, and cloud environments.

Migration Steps

Follow this timeline for a safe, zero-downtime migration:

1. Test in Parallel

Deploy scry-proxy alongside PgBouncer on a different port. Route a percentage of read traffic through scry-proxy and compare behavior. Use the --pgbouncer-config flag to ensure identical pool settings.

2. Verify Behavior

Compare query latencies, connection counts, and error rates between both proxies. Check that prepared statements, transactions, and your application's edge cases work correctly.

3. Switch Traffic

Update your application connection strings or load balancer to point to scry-proxy. For gradual rollout, use weighted routing to shift traffic incrementally (10%, 50%, 100%).

4. Monitor

Watch the new metrics dashboards for anomalies. Pay attention to connection pool utilization, query latency percentiles, and circuit breaker state. Keep PgBouncer running but idle for quick rollback.

# Example: Run scry-proxy on port 6432 while PgBouncer stays on 5432
./scry-proxy --pgbouncer-config /etc/pgbouncer/pgbouncer.ini \
    --listen-port 6432

# Verify with a test connection
psql -h localhost -p 6432 -U myuser -d mydb -c "SELECT 1"

Rollback

If you encounter issues, rollback is instantaneous:

# Stop scry-proxy
systemctl stop scry-proxy

# Start PgBouncer (if not already running)
systemctl start pgbouncer

# Update DNS/load balancer to point back to PgBouncer port

Since both proxies can run simultaneously, you can keep PgBouncer warm and ready. Simply redirect traffic back to PgBouncer's port and your applications will reconnect automatically.

Note: Keep your PgBouncer configuration and service intact during the migration period. Only decommission PgBouncer after you've run scry-proxy successfully in production for your desired validation period.

Ready to Migrate?

Get started with scry-proxy today and unlock powerful observability for your PostgreSQL infrastructure.

Request Early Access