HeliosProxy Documentation

Programmable Postgres Data-Plane

---

What is HeliosProxy?

HeliosProxy is a programmable Postgres data-plane: a PostgreSQL-wire connection router with a real WASM plugin runtime, signed plugin distribution via OCI, a transaction journal with operator-driven replay, a zero-downtime PostgreSQL major-version upgrade orchestrator, and a built-in admin web console.

Capabilities are organised into two tiers:

• Connection-Routing Tier — read/write splitting, health checking, circuit breaking, rate limiting, connection pooling (session / transaction / statement), and failover.
• Platform Tier — WASM plugins, query caching, query analytics, multi-tenancy, authentication, query rewriting, GraphQL and MCP gateways, anomaly detection, and edge/geo caching.

Every tier-two capability is a Cargo feature flag, so the binary only carries what you enable — see Feature Flags for the authoritative list, which tracks the [features] table in Cargo.toml flag for flag.

The project’s stated policy is that every feature flag in a release does real work, with intentionally-bounded capabilities documented rather than implied. Where a subsystem is library-only or not yet mounted on the per-query data path, this documentation says so explicitly.

Quick Start

Run with Docker

# latest follows the newest release; pin a release tag in production
docker pull ghcr.io/heliosdatabase/hdb-heliosdb-proxy:latest

docker run -d \
  --name heliosproxy \
  -p 5432:5432 \
  -v $(pwd)/proxy.toml:/etc/helios/proxy.toml:ro \
  ghcr.io/heliosdatabase/hdb-heliosdb-proxy:latest

The image reads its configuration from /etc/helios/proxy.toml. Published tags follow the releases (each release version, its major.minor line, and latest). The admin API binds loopback by default, so with the configuration below it is reachable only from inside the container (docker exec); to publish port 9090, set admin_address = "0.0.0.0:9090" together with admin_token. See Docker Deployment.

Install from crates.io

cargo install heliosdb-proxy

The minimum supported Rust version is 1.86.

Configure

Minimal proxy.toml:

listen_address = "0.0.0.0:5432"
admin_address  = "127.0.0.1:9090"
tr_enabled     = true
tr_mode        = "session"

[pool]
min_connections      = 2
max_connections      = 100
idle_timeout_secs    = 300
max_lifetime_secs    = 1800
acquire_timeout_secs = 30
test_on_acquire      = true

[load_balancer]
read_strategy        = "round_robin"
read_write_split     = true
latency_threshold_ms = 100

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

[[nodes]]
name    = "primary-1"
host    = "pg-primary.example.com"
port    = 5432
role    = "primary"
weight  = 100
enabled = true

[[nodes]]
name    = "standby-1"
host    = "pg-standby.example.com"
port    = 5432
role    = "standby"
weight  = 100
enabled = true

At least one [[nodes]] entry must have role = "primary"; the optional subsystems (cache, gateways, plugins, multi-tenancy and so on) stay off unless you enable them. Config files support ${VAR} and ${VAR:-default} environment substitution, and a ${VAR} with no default and no environment value fails fast at load.

See Configuration for the full reference, and the repo’s config/ directory for complete example files.

Topology

                  ┌─────────────┐
                  │ HeliosProxy │  ← WASM plugins, replay engine,
                  │             │    upgrade orchestrator, admin UI
                  └──────┬──────┘
                         │  PostgreSQL wire protocol
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐      ┌─────────┐      ┌─────────┐
   │ Primary │      │ Standby │      │ Replica │
   └─────────┘      └─────────┘      └─────────┘

The upgrade orchestrator’s validation stage uses a row-count parity check that is portable across PostgreSQL 14–18. Release verification runs against PostgreSQL 18.4.

Documentation Structure

• Architecture — System design, request lifecycle, hook points
• Configuration — Full proxy.toml reference, including [limits], [anomaly], [cache], [auth], [tls] and [[hba]]
• Feature Flags — Cargo features and module activation
• Admin API — REST endpoints (topology, plugins, plugin KV, anomalies, edge, chaos, migration, replay, metrics)
• Topology Providers — Backend discovery and write authority (static roles, PostgreSQL polling with the timeline rule, Patroni)
• Transaction Replay — In-session failover (tr_mode), the committed-transaction journal ([journal]) and operator replay (POST /api/replay, including committed_history); all in the default build
• Deployment Guides — Docker, Kubernetes, standalone
• Release History — Changes by release, upgrade notes and the earlier release notes

Source Repositories

Repository	Role	License
HeliosDB-Proxy	Core proxy (this is where most files live)	Apache-2.0
HeliosDB-Proxy-Plugins	First-party WASM plugins + helios-plugin CLI	Apache-2.0
HeliosDB-Proxy-Operator	Kubernetes operator + Helm chart	Not currently public
terraform-provider-HeliosDB-Proxy	Terraform provider	Not currently public
pulumi-HeliosDB-Proxy	Pulumi provider	Not currently public

Container image: ghcr.io/heliosdatabase/hdb-heliosdb-proxy (lowercase due to GHCR convention), with a tag per release and latest. The project was first published under the Dimensigon GitHub organisation; those older paths are no longer valid.

Releases

Changes by release, upgrade notes for each major version and the earlier release notes are on the Release History page. The repository CHANGELOG is the complete record.

Examples & Demos

End-to-end demo runners live in the core repo’s examples/ directory:

• examples/postgres-cluster — full PG-cluster + proxy compose
• examples/failover-demo — manual failover with Transaction Replay
• examples/multi-tenant — per-tenant pool isolation

The platform-tier feature demos remain in the repository’s demos/ directory and are catalogued under Demos.