HeliosProxy

High-performance connection router, intelligent query processor, and failover manager for PostgreSQL-wire-compatible databases.

HeliosProxy operates at the PostgreSQL wire protocol level, making it compatible with any database that speaks the PostgreSQL protocol — including PostgreSQL, HeliosDB, CockroachDB, YugabyteDB, and others.

Overview

HeliosProxy sits between your application and your database cluster, providing transparent connection pooling, automatic failover, intelligent query routing, and 24 enterprise-grade feature modules — all without application code changes.

┌──────────────┐     ┌─────────────────────────────────────────────────┐     ┌──────────────┐
│              │     │                  HeliosProxy                    │     │   Primary    │
│  Application ├────►│                                                 ├────►│   (R/W)      │
│              │     │  ┌───────────┐ ┌──────────┐ ┌───────────────┐  │     └──────────────┘
│  (psql, any  │     │  │Connection │ │  Query   │ │   Failover    │  │     ┌──────────────┐
│   PG driver) │     │  │  Pooling  │ │ Routing  │ │  Controller   │  ├────►│  Standby     │
│              │     │  └───────────┘ └──────────┘ └───────────────┘  │     │  (Sync)      │
└──────────────┘     │  ┌───────────┐ ┌──────────┐ ┌───────────────┐  │     └──────────────┘
                     │  │  Caching  │ │   Auth   │ │  Rate Limit   │  │     ┌──────────────┐
                     │  │  (L1/L2)  │ │  Proxy   │ │  & Circuit    │  ├────►│  Standby     │
                     │  └───────────┘ └──────────┘ └───────────────┘  │     │  (Async)     │
                     └─────────────────────────────────────────────────┘     └──────────────┘

Key Capabilities

Protocol-Level Compatibility

All 24 feature modules operate at the PostgreSQL wire protocol level. They inspect, route, cache, and transform queries without requiring changes to your application or database. Any client library that connects to PostgreSQL connects to HeliosProxy.

Supported Backends

Feature Modules

HeliosProxy ships 24 feature modules, each independently enabled via Cargo feature flags. Enable only what you need — from a lightweight connection pooler to a full-featured intelligent proxy.

Connection Management

High Availability

Query Intelligence

Security & Access Control

Multi-Tenancy & Extensibility

Distributed Caching

Quick Start

Connect to a PostgreSQL Cluster

heliosdb-proxy --config proxy.toml

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

[pool]
mode = "transaction"
min_connections = 5
max_connections = 100
idle_timeout_secs = 300

[load_balancer]
strategy = "least_connections"
read_write_split = true

[health]
check_interval_secs = 5
check_query = "SELECT 1"
failure_threshold = 3

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

[[nodes]]
host = "pg-standby-sync.internal"
port = 5432
role = "standby"
sync = true

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

Connect Your Application

# HeliosProxy is transparent — use any PostgreSQL client
psql -h localhost -p 6432 -U myapp -d mydb

# Or set DATABASE_URL
export DATABASE_URL="postgres://myapp:password@localhost:6432/mydb"

Feature Flags

Build Examples

# Default — connection pooling only
cargo build --release

# Production — all features with PostgreSQL topology
cargo build --release --features "all-features,postgres-topology"

# Lightweight — pooling + failover only
cargo build --release --features "pool-modes,ha-tr"

# With HeliosDB integration
cargo build --release --features "all-features,heliosdb-topology"

Topology Providers

HeliosProxy supports pluggable topology discovery for automatic primary tracking:

PostgreSQL (postgres-topology)

Polls pg_is_in_recovery() on each configured node to detect the current primary. Compatible with any PostgreSQL HA solution:

• Native streaming replication — standard PostgreSQL primary/standby
• Patroni — automatic failover with etcd/ZooKeeper
• pg_auto_failover — Citus-managed automatic failover
• Stolon — cloud-native PostgreSQL HA
• AWS RDS / Aurora — managed PostgreSQL

HeliosDB (heliosdb-topology)

Integrates with the HeliosDB internal topology manager for event-driven primary tracking. Zero-polling, instant failover detection.

Manual / API

Set and update the primary programmatically via the Admin API — suitable for custom orchestration or external failover managers.

Admin API

# Cluster health
curl http://localhost:9090/health

# Node status and replication lag
curl http://localhost:9090/nodes

# Connection pool metrics
curl http://localhost:9090/metrics

# Trigger manual failover
curl -X POST http://localhost:9090/failover

# Drain node for maintenance
curl -X POST http://localhost:9090/nodes/{id}/drain

Deployment

Standalone Binary

cargo install heliosdb-proxy
heliosdb-proxy --config /etc/heliosproxy/proxy.toml

Docker

FROM rust:1.82 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release --features "all-features,postgres-topology"

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/heliosdb-proxy /usr/local/bin/
ENTRYPOINT ["heliosdb-proxy"]

docker run -v /etc/heliosproxy:/config heliosdb-proxy --config /config/proxy.toml

Kubernetes Sidecar

Deploy as a sidecar container for minimal latency between your application and the proxy:

containers:
  - name: app
    image: myapp:latest
    env:
      - name: DATABASE_URL
        value: "postgres://user:pass@localhost:6432/mydb"
  - name: heliosproxy
    image: heliosdb/heliosproxy:latest
    args: ["--config", "/config/proxy.toml"]
    ports:
      - containerPort: 6432
      - containerPort: 9090

Benchmarks

HeliosProxy adds minimal overhead while providing significant throughput improvements through connection pooling, query caching, and pipelining:

License

Apache-2.0 (Apache License, Version 2.0).