Configuration

ScryData follows 12-factor app methodology. Configure via environment variables or config file for flexible deployment.

Configuration Priority

Configuration is loaded in priority order (highest to lowest):

Environment Variables (SCRY_*)
         |
         v
Configuration File (scry.toml)
         |
         v
Default Values

This allows you to set defaults in scry.toml and override specific values with environment variables in production.

Environment Variables

All configuration options can be set via environment variables with the SCRY_ prefix. Nested configuration uses double underscores (__):

# proxy.listen_address -> SCRY_PROXY__LISTEN_ADDRESS
export SCRY_PROXY__LISTEN_ADDRESS="127.0.0.1:5433"

# backend.host -> SCRY_BACKEND__HOST
export SCRY_BACKEND__HOST="localhost"

# resilience.circuit_breaker.enabled -> SCRY_RESILIENCE__CIRCUIT_BREAKER__ENABLED
export SCRY_RESILIENCE__CIRCUIT_BREAKER__ENABLED=true

PgBouncer Compatibility

ScryData can read existing PgBouncer configuration files, making migration seamless. Use the --pgbouncer-config flag or SCRY_PGBOUNCER_CONFIG environment variable:

# Via command line flag
scry-proxy --pgbouncer-config /etc/pgbouncer/pgbouncer.ini

# Via environment variable
export SCRY_PGBOUNCER_CONFIG="/etc/pgbouncer/pgbouncer.ini"
scry-proxy

ScryData will parse your PgBouncer configuration and map settings to equivalent ScryData options. Settings defined in your native scry.toml or environment variables take precedence over PgBouncer config values.

For a complete migration guide, see Migrating from PgBouncer.

Connection Pooling Strategies

ScryData supports multiple connection pooling strategies to match your workload characteristics:

Strategy Description Use Case
disabled No pooling, 1:1 client-to-backend connections Debugging, legacy apps requiring dedicated connections
session Connection held for entire client session Applications using session-level state (temp tables, prepared statements)
transaction Connection released after each transaction High-concurrency workloads, PgBouncer compatibility mode
hybrid (default) Dynamic pinning with automatic state tracking Best of both worlds - multiplexes when possible, pins when needed 
[backend]
pool_mode = "hybrid"  # or "disabled", "session", "transaction"

TLS Configuration

ScryData supports TLS for both client-facing connections and backend database connections.

Client-Facing TLS

Configure TLS for connections from your applications to ScryData:

Parameter Default Description
client_tls_sslmode disable TLS mode: disable, allow, prefer, require
client_tls_cert_file — Path to server certificate file
client_tls_key_file — Path to server private key file 
[proxy]
client_tls_sslmode = "require"
client_tls_cert_file = "/etc/scry/server.crt"
client_tls_key_file = "/etc/scry/server.key"

Backend TLS

Configure TLS for connections from ScryData to your PostgreSQL database:

Parameter Default Description
server_tls_sslmode prefer TLS mode: disable, allow, prefer, require, verify-ca, verify-full
server_tls_ca_file — Path to CA certificate for server verification 
[backend]
server_tls_sslmode = "verify-full"
server_tls_ca_file = "/etc/scry/ca.crt"

Authentication

ScryData supports multiple authentication methods for client connections:

Parameter Default Description
auth_type md5 Authentication method: trust, md5, scram-sha-256, cert
auth_file — Path to userlist file (PgBouncer format)
auth_query — SQL query to fetch user credentials from database

Authentication Types

  • trust: No authentication required (development only)
  • md5: MD5 password hashing (legacy compatibility)
  • scram-sha-256: SCRAM-SHA-256 (recommended for production)
  • cert: Client certificate authentication

Auth File Format

The auth file uses PgBouncer's userlist.txt format for compatibility:

# userlist.txt format
# "username" "password"
"postgres" "md5abc123..."
"app_user" "SCRAM-SHA-256$4096:salt$stored_key:server_key"
"readonly" "plaintext_password"

Auth Query

Alternatively, fetch credentials dynamically from PostgreSQL:

[auth]
auth_type = "scram-sha-256"
auth_query = "SELECT username, password FROM pg_shadow WHERE username=$1"

Complete Configuration Example

[proxy]
listen_address = "127.0.0.1:5433"
max_connections = 100
shutdown_timeout_secs = 30

[backend]
protocol = "Postgres"
host = "localhost"
port = 5432
database = "postgres"
user = "postgres"
password = "postgres"
pool_size = 10
connection_timeout_ms = 5000

[observability]
enable_tracing = true
service_name = "scry-proxy"
metrics_server_address = "127.0.0.1:9090"
enable_metrics_server = true

[publisher]
enabled = true
batch_size = 100
flush_interval_ms = 1000
anonymize = true
publisher_type = "debug"
max_queue_size = 10000

[resilience.circuit_breaker]
enabled = true
failure_threshold = 5
success_threshold = 2
open_timeout_secs = 60
use_health_monitor = true

[resilience.connection_retry]
enabled = true
max_attempts = 3
initial_backoff_ms = 50
max_backoff_ms = 5000
backoff_multiplier = 2.0
jitter_factor = 0.1

[resilience.healthcheck]
active_enabled = true
interval_secs = 30
timeout_ms = 1000
failure_threshold = 3

[health]
error_rate_spike_factor = 3.0
latency_spike_factor = 2.0
pool_saturation_threshold = 0.95
ema_alpha = 0.1

Proxy Settings

Parameter Default Description
listen_address 127.0.0.1:5433 Address and port for proxy to listen on
max_connections 100 Maximum concurrent client connections
shutdown_timeout_secs 30 Seconds to wait for graceful shutdown

Backend Database Settings

Parameter Default Description
protocol Postgres Database protocol
host localhost Backend database hostname
port 5432 Backend database port
database — Database name to connect to
user — Database username
password — Database password
pool_size 10 Size of backend connection pool
connection_timeout_ms 5000 Connection timeout in milliseconds

Publisher Settings

Parameter Default Description
enabled true Enable event publishing
batch_size 100 Events per batch before flush
flush_interval_ms 1000 Milliseconds between flushes
anonymize true Anonymize queries before publishing
publisher_type debug Publisher type: "debug" or "http"
max_queue_size 10000 Max queued events before dropping

Common Scenarios

Development Environment

[publisher]
publisher_type = "debug"  # Log to console
anonymize = false         # See actual query values

[resilience.circuit_breaker]
failure_threshold = 3     # More sensitive
open_timeout_secs = 10    # Faster recovery

Production Environment

[proxy]
listen_address = "0.0.0.0:5433"
max_connections = 1000

[backend]
pool_size = 50

[publisher]
publisher_type = "http"
anonymize = true          # Privacy protection
batch_size = 250          # Larger batches

[resilience.circuit_breaker]
failure_threshold = 10    # Less sensitive
open_timeout_secs = 120   # Longer recovery period

High-Availability Setup

[backend]
pool_size = 100
connection_timeout_ms = 3000

[resilience.circuit_breaker]
failure_threshold = 15
use_health_monitor = true

[resilience.connection_retry]
max_attempts = 5
max_backoff_ms = 10000

[resilience.healthcheck]
interval_secs = 15
failure_threshold = 5

Ready to Configure ScryData?

Get early access and start protecting your database migrations.

Request Early Access