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.

The current release is 1.6.0 (September 4, 2026). 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.

Since 1.0.0 the project’s stated policy is that every shipped feature flag 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

docker pull ghcr.io/heliosdatabase/hdb-heliosdb-proxy:1.6.0

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

Published tags follow the release tags (1.6.0, 1.6, latest). Note that the admin API binds loopback by default as of 1.4.0, so reach it from inside the container or publish it deliberately as above.

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"

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

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

The sections [pool], [load_balancer], [health] and at least one [[nodes]] entry are required in a configuration file; everything else defaults to off. Config files support ${VAR} and ${VAR:-default} environment substitution (1.4.0), 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,
                  │   v1.6.0    │    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 (PostgreSQL polling, HeliosDB native)
Transaction Replay — In-session failover (tr_mode) and the journal-backed replay engine
Deployment Guides — Docker, Kubernetes, standalone

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:1.6.0 (lowercase due to GHCR convention). The project was published under the Dimensigon organisation before 0.5.1; those older paths are no longer valid.

What’s New

Highlights since 0.4.0 — see the repo CHANGELOG for the complete history.

1.6.0 — tr_mode now drives real in-session failover on both query protocols; backend faults return a proper PostgreSQL ErrorResponse instead of a dropped socket; SCRAM/MD5/cleartext backend authentication on redial; new [limits] and [cache] bounds; per-query hot-path performance work.
1.5.0 — [limits] and [anomaly] configuration sections; /admin/kv/<plugin>/<key> endpoints for pushing plugin runtime config; /healthz, /livez, /readyz probe routes; admin dashboard fixed to work with admin_token set. Contains a stored-XSS fix for the 1.4.0 admin dashboard — 1.4.0 operators should upgrade.
1.4.0 — Admin API binds loopback by default (breaking); environment-variable substitution in config files; edge/geo result-cache mode; MCP bearer auth; gateway and admin request hardening.
1.3.0 / 1.3.1 — In-band failure detection, protocol-level health probes, /api/circuit, idle-connection reaper.
1.2.0 — Real LDAP search-then-bind authentication (ldap-auth).
1.1.0 — Transaction and statement pooling do real work on the data path.
1.0.0 — First stable release; every feature flag ships working functionality, with bounded capabilities documented.
0.5.0 — Client TLS/mTLS, proxy-terminated SCRAM-SHA-256, pg_hba-style admission rules, MCP agent gateway, HTTP SQL gateway, admin bearer auth, SIGHUP reload and SIGUSR2 binary handoff.
v0.4.0 — From Connection Router to Programmable Data-Plane — historical release note
v0.3.1 — Hot-path Performance & Correctness — historical release note

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 v0.4.0 feature demos remain in demos/v0.4.0/ and are catalogued under Demos.