--- title: "HeliosProxy: Beyond PgBouncer" description: "Our flagship connection router with multi-tier caching, GraphQL gateway, WASM plugins, and intelligent query routing." date: 2025-10-22 updated: 2025-10-22 tag: "Architecture" canonical: https://www.heliosdb.com/blog/heliosproxy-beyond-pgbouncer.html --- # 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](https://www.heliosdb.com/blog/heliosproxy-1-7-0-verified-transaction-replay.html) and the [Transaction Replay reference](https://www.heliosdb.com/docs/proxy/transaction-replay/) 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.