HeliosProxy: Beyond PgBouncer

Historical design note (2025). The Transaction Replay section below does not describe shipping behaviour. Transaction Replay is not gated on the ha-tr cargo feature — in-session recovery is core — and the [transaction_replay] TOML block shown never shipped; the real keys are top-level tr_enabled / tr_mode / write_timeout_secs plus [limits]. See HeliosProxy 1.7.0 and the Transaction Replay reference for current behaviour.

Connection pooling is table stakes. PgBouncer does it well, and ProxySQL adds query routing for MySQL. But modern applications need much more from their database proxy: intelligent caching, rate limiting, circuit breaking, query analytics, multi-tenancy, and seamless failover. That's why we built HeliosProxy — a purpose-built connection router with 18 enterprise features in a single component.

Why Another Proxy?

PgBouncer is excellent at what it does — connection multiplexing. But it treats all queries equally, has no caching, no query-level routing, and no awareness of your application's workload patterns. We found ourselves deploying PgBouncer + Redis + HAProxy + custom middleware, each with its own configuration and failure modes.

HeliosProxy replaces this entire stack with a single component that understands your queries, your tenants, and your performance requirements.

Multi-Tier Caching (L1/L2/L3)

HeliosProxy implements three levels of query caching, all with WAL-based invalidation:

# heliosproxy.toml
[cache]
l1_enabled = true       # Local exact-match cache (per-proxy instance)
l1_max_entries = 10000
l1_ttl_ms = 5000

l2_enabled = true       # Distributed normalized-query cache
l2_backend = "cluster"  # Shared across proxy instances

l3_enabled = true       # Semantic similarity cache
l3_similarity = 0.95    # Match queries with 95%+ similarity

L1 (Exact Match): Caches query results keyed by the exact SQL string + parameters. Sub-microsecond lookup. Ideal for hot queries like session lookups.

L2 (Normalized): Normalizes queries (strips literal values, canonicalizes whitespace) and caches results. Catches variations of the same query pattern across tenants.

L3 (Semantic): Uses vector similarity to match queries that are semantically equivalent but syntactically different. "SELECT name FROM users WHERE id = 5" matches "SELECT name FROM users WHERE id = 42" because the query structure is identical.

Transparent Write Routing (TWR)

Connect to any node — primary or standby — and HeliosProxy automatically routes write operations to the primary. Applications never need to maintain separate read/write connection strings:

[transparent_write_routing]
enabled = true
sync_mode = "sync"        # sync | semisync | async
forward_timeout_ms = 5000

[transparent_write_routing.pool]
max_connections = 50
idle_timeout_ms = 60000

Transaction Replay (TR)

Oracle-grade TAF+TAC for PostgreSQL. HeliosProxy journals all statements within a transaction and automatically replays them on a new node after failover:

[transaction_replay]
enabled = true
verify_results = true         # Checksum verification on replay
max_retries = 3
wait_for_wal_sync = true      # Ensure standby is caught up

Rate Limiting

[rate_limiting]
enabled = true
strategy = "token_bucket"     # token_bucket | sliding_window | concurrency
default_qps = 1000
burst_multiplier = 2.0

# Per-tenant overrides
[[rate_limiting.overrides]]
tenant = "enterprise-customer"
qps = 10000

Circuit Breaker

[circuit_breaker]
enabled = true
failure_threshold = 5         # Failures before opening circuit
reset_timeout_ms = 30000      # Time before half-open attempt
half_open_max_requests = 3    # Requests to test in half-open state

Query Analytics

[query_analytics]
enabled = true
slow_query_threshold_ms = 100
fingerprint_queries = true    # Normalize for pattern analysis
histogram_buckets = [1, 5, 10, 25, 50, 100, 250, 500, 1000]
# Tracks P50, P90, P95, P99 per query fingerprint

Feature Architecture

HeliosProxy is built as a layered feature set with clean dependency management:

[features]
ha-proxy = ["ha-innovations"]         # Base proxy
ha-tr = ["ha-proxy", "ha-tier1"]      # Transaction Replay
pool-modes = ["ha-proxy"]             # Session/Transaction/Statement pooling
query-cache = ["ha-proxy"]            # L1/L2/L3 caching
routing-hints = ["ha-proxy"]          # SQL comment routing hints
lag-routing = ["ha-proxy"]            # Replica lag-aware routing
rate-limiting = ["ha-proxy"]          # Multi-dimensional rate limits
circuit-breaker = ["ha-proxy"]        # Fault tolerance
query-analytics = ["ha-proxy"]        # Slow query analysis
multi-tenancy = ["ha-proxy"]          # Tenant isolation
auth-proxy = ["ha-proxy"]             # JWT/OAuth/API key auth
query-rewriting = ["ha-proxy"]        # Pattern/regex/AST rewriting
wasm-plugins = ["ha-proxy"]           # WASM extensibility
graphql-gateway = ["ha-proxy"]        # Auto-generated GraphQL
schema-routing = ["ha-proxy"]         # Hot/warm/cold routing
distribcache = ["ha-proxy"]           # Distributed cache

Routing Hints

Applications can control routing via SQL comments without changing query logic:

-- Force read from primary (for read-your-writes consistency)
/* helios:route=primary */ SELECT * FROM orders WHERE id = 42;

-- Route to standby (for analytical queries)
/* helios:route=standby */ SELECT COUNT(*) FROM orders GROUP BY status;

-- Use TWR (transparent write routing)
/* helios:route=twr */ INSERT INTO orders (user_id, total) VALUES (1, 99.99);

HeliosProxy is included in HeliosDB Professional (basic) and Enterprise (full 18-feature suite). It's the single most impactful component for organizations running HeliosDB in production.

← Back to Blog