HeliosProxy

Intelligent Connection Router for PostgreSQL-Wire-Compatible Databases

Protocol-Level. Zero Application Changes.

HeliosProxy is a high-performance connection router that operates entirely at the PostgreSQL wire protocol level. Every feature module — from connection pooling to AI-powered distributed caching — works transparently with any database that speaks the PostgreSQL protocol.

Deploy HeliosProxy between your application and your database cluster. Your application connects to HeliosProxy exactly as it would connect to PostgreSQL. No driver changes. No code changes. No vendor lock-in.

Application  ──►  HeliosProxy  ──►  PostgreSQL / HeliosDB / CockroachDB / YugabyteDB
   (any PG          (24 feature         (any PostgreSQL-wire-compatible
    driver)           modules)            backend)

Why HeliosProxy

Before HeliosProxy

Managing a production database cluster requires assembling multiple tools — a connection pooler (PgBouncer), a load balancer (HAProxy), a failover manager (Patroni), a caching layer (Redis), an auth proxy, and monitoring. Each tool adds operational complexity, configuration drift, and failure modes.

With HeliosProxy

A single binary replaces the entire stack. Enable only the features you need, from a minimal connection pooler to a fully-featured intelligent proxy with query caching, automatic failover, and real-time analytics.

Concern	Traditional Stack	HeliosProxy
Connection pooling	PgBouncer	Built-in (Session/Transaction/Statement)
Load balancing	HAProxy	Built-in (round-robin, least-connections, latency-based)
Failover	Patroni + scripts	Built-in (automatic, with Transaction Replay)
Query caching	Redis + app code	Built-in (L1/L2/L3 multi-tier)
Authentication	Custom middleware	Built-in (JWT, OAuth 2.0, API keys, LDAP)
Rate limiting	nginx / custom	Built-in (token bucket, sliding window)
Monitoring	Separate exporters	Built-in (Prometheus, OpenTelemetry)

Supported Backends

All features operate at the wire protocol level and are backend-agnostic:

Backend	Compatibility	Notes
PostgreSQL 12+	Full	Including Amazon RDS, Aurora, Cloud SQL, Azure Database
HeliosDB-Lite	Full	Optional native topology integration for instant failover
HeliosDB-Full	Full	Cluster-aware routing with replication topology events
CockroachDB	Full	PostgreSQL wire protocol compatible
YugabyteDB	Full	PostgreSQL wire protocol compatible
TimescaleDB	Full	Runs as PostgreSQL extension
Citus	Full	Runs as PostgreSQL extension
AlloyDB	Full	Google Cloud PostgreSQL-compatible

24 Feature Modules

Each module is independently activated via a compile-time feature flag. Enable only what your deployment requires — no unused code ships in your binary.

Connection Management

Connection Pooling (pool-modes) Session, Transaction, and Statement pooling modes with automatic lease management, prepared statement forwarding, and configurable connection reset sequences. Eliminates connection overhead and reduces backend load.

Load Balancer (always available) Distributes queries across cluster nodes using round-robin, least-connections, or latency-based strategies. Automatic read/write splitting routes SELECT queries to standbys and writes to the primary.

Health Checker (always available) Monitors every node with configurable health-check queries, failure thresholds, and recovery detection. Unhealthy nodes are automatically removed from the routing pool and re-added when they recover.

Request Pipeline (always available) Supports PostgreSQL extended query protocol pipelining. Batches Parse, Bind, and Execute messages to reduce network round trips, improving throughput for high-frequency workloads.

Batch Operations (always available) Automatically coalesces individual INSERT statements targeting the same table into multi-row batch inserts, significantly increasing write throughput without application changes.

High Availability & Failover

Failover Controller (always available) Automatic failover with configurable promotion policies. Prefers synchronous standbys, ranks candidates by replication lag, and coordinates with the switchover buffer to ensure zero dropped queries during promotion.

Transaction Replay (TR) (ha-tr) The signature HA feature. Journals every statement of in-flight transactions in real time. When a primary fails, pending transactions are transparently replayed on the newly promoted primary. Clients experience a brief pause — not an error.

Session Migration (ha-tr) Captures full session state — SET parameters, prepared statements, search paths, and advisory locks — and replays them on the new primary. Sessions resume transparently after failover.

Cursor Restore (ha-tr) Preserves open server-side cursor positions across failover events. Clients calling FETCH NEXT continue receiving rows from the correct position without re-executing the original query.

Switchover Buffer (always available) During planned switchover or automatic failover, incoming queries are buffered in memory and drained to the new primary once promotion completes. Applications experience increased latency, not errors.

Primary Tracker (always available) Pluggable topology discovery with three modes:

PostgreSQL: Polls pg_is_in_recovery() on each node to detect the current primary. Compatible with Patroni, pg_auto_failover, Stolon, and native streaming replication.
HeliosDB: Subscribes to internal topology change events for instant, zero-polling failover detection.
Manual: Set the primary via the Admin API for custom orchestration.

Transaction Journal (ha-tr) Write-ahead journal for in-flight transactions with statement-level granularity, full parameter capture, and configurable retention policies.

Query Intelligence

Query Cache (query-cache) Three-tier result cache that eliminates redundant backend queries:

L1 Hot: In-memory LRU cache for frequently accessed results (sub-microsecond)
L2 Warm: Larger capacity cache with TTL-based expiration
L3 Semantic: Normalized query matching that recognizes equivalent queries with different parameter values

Query Routing Hints (routing-hints) Embed routing directives in SQL comments to control query placement:

/*+ route=primary */ SELECT * FROM orders WHERE id = 42;
/*+ route=standby */ SELECT count(*) FROM events;
/*+ route=nearest */ SELECT * FROM config;

Lag-Aware Routing (lag-routing) Routes read queries to replicas within a configurable replication lag threshold. Includes read-your-writes (RYW) consistency: after a write, subsequent reads from the same session are routed to the primary until the replica catches up.

Query Rewriter (query-rewriting) Rule-based SQL transformation engine. Define rewrite rules that match query patterns and apply transformations before queries reach the backend — add optimizer hints, redirect tables, inject filters, or enforce naming conventions.

Query Analytics (query-analytics) Real-time query intelligence:

Fingerprinting: Groups queries by normalized pattern regardless of parameter values
Slow Query Log: Captures queries exceeding configurable duration thresholds
Intent Classification: Classifies queries as OLTP, analytics, vector search, RAG, or embedding operations
N+1 Detection: Identifies repeated similar queries indicative of N+1 query patterns

Schema-Aware Routing (schema-routing) Routes queries based on table metadata and access patterns:

Data Temperature: Classifies tables as hot, warm, cold, or frozen based on access frequency
Workload Type: Detects OLTP, analytics, and vector workloads for specialized routing
Discovery: Automatically introspects backend schema to inform routing decisions

Security & Access Control

Authentication Proxy (auth-proxy) Centralized authentication gateway:

JWT: Validate and decode JSON Web Tokens with configurable claim mapping
OAuth 2.0: Token introspection and exchange with external identity providers
API Keys: Managed API key issuance, rotation, and revocation with configurable prefixes
LDAP: Directory-based authentication with group-to-role mapping
Role Mapping: Map external identity claims to database roles and permissions

Rate Limiter (rate-limiting) Protects backends from overload:

Token Bucket: Smooth rate limiting with configurable burst capacity
Sliding Window: Fixed-window rate limiting with sub-window granularity
Concurrency Limiter: Caps concurrent query execution per user, tenant, or IP
Query Cost Estimator: Weights rate limit consumption by estimated query cost

Circuit Breaker (circuit-breaker) Adaptive circuit breaker for each backend node:

Sliding Window: Failure rate calculation over a configurable time window
State Machine: Closed, Open, and Half-Open states with automatic recovery probes
Adaptive Thresholds: Adjusts failure thresholds based on observed traffic patterns

Multi-Tenancy & Extensibility

Multi-Tenancy (multi-tenancy) Tenant-aware connection management:

Tenant Identification: Extract tenant identity from connection parameters, certificates, or application-name
Pool Isolation: Dedicated connection pools per tenant with independent sizing
Schema Isolation: Route tenants to dedicated schemas or databases
Resource Quotas: Per-tenant connection limits, query rate limits, and resource caps

WASM Plugin System (wasm-plugins) Extend HeliosProxy with sandboxed WebAssembly plugins:

Hot Reload: Deploy and update plugins without proxy restart
Sandboxed Execution: Plugins run in isolated WASM runtimes with memory limits
Host Functions: Plugins access proxy state through a controlled API
Use Cases: Custom authentication, query transformation, audit logging, metrics export

GraphQL Gateway (graphql-gateway) Expose your database as a GraphQL API:

Automatic Introspection: Generates a GraphQL schema from database tables
SQL Generation: Translates GraphQL queries into optimized SQL
DataLoader Batching: Automatically batches N+1 field resolution into batch queries
Query Validation: Validates incoming GraphQL against the introspected schema

Distributed Caching

DistribCache (distribcache) AI-powered distributed query cache for multi-node proxy deployments:

Three-Tier Storage: Hot (in-process), warm (shared memory), distributed (network)
Workload Classification: Classifies queries as transactional, analytical, or AI/ML for tier selection
Access Heatmap: Tracks access frequency to prioritize cache placement
Intelligent Prefetching: Predicts and preloads query results based on access patterns
RAG Integration: Specialized caching for embedding lookups and vector search results

Getting Started

Installation

# From source
cargo install heliosdb-proxy

# With all features + PostgreSQL topology
cargo install heliosdb-proxy --features "all-features,postgres-topology"

Minimal Configuration

[proxy]
listen_address = "0.0.0.0:6432"
admin_address = "0.0.0.0:9090"

[[nodes]]
host = "db-primary.internal"
port = 5432
role = "primary"

[[nodes]]
host = "db-standby.internal"
port = 5432
role = "standby"

Connect

# Any PostgreSQL client works
psql -h localhost -p 6432 -U myapp -d mydb

# Any PostgreSQL driver works
DATABASE_URL=postgres://myapp:password@localhost:6432/mydb

Admin API

HeliosProxy exposes a REST API on the admin port (default 9090):

Endpoint	Method	Description
`/health`	GET	Proxy and cluster health status
`/nodes`	GET	Node status, roles, and replication lag
`/metrics`	GET	Connection pool, query, and cache metrics
`/failover`	POST	Trigger manual failover
`/nodes/{id}/drain`	POST	Drain a node for maintenance
`/config/reload`	POST	Reload configuration without restart

Deployment Options

Method	Best For
Standalone binary	Traditional VM or bare-metal deployments
Docker container	Container orchestration environments
Kubernetes sidecar	Minimal latency, per-pod proxy instances
Kubernetes Deployment	Shared proxy pool for multiple services

Performance

HeliosProxy adds minimal latency while significantly improving throughput:

Metric	Direct Connection	With HeliosProxy
Connection establishment	12ms	0.3ms (pooled)
Query throughput	8,200 q/s	42,000 q/s (pooled)
Cached query latency	—	0.05ms
Failover duration	Manual intervention	1.2s automatic

Learn More

Quick Start Guide — Set up HeliosProxy in 5 minutes
API Reference — REST API documentation
Configuration Reference — Full configuration file documentation
Examples — Production deployment patterns

HeliosProxy is part of the HeliosDB product family. Licensed under SSPL-1.0.