HeliosProxy Documentation

Programmable Postgres Data-Plane

What is HeliosProxy?

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

As of v0.4.0 (April 25, 2026) the platform ships 46 feature modules — 24 v0.3 connection-routing modules + 22 v0.4 platform modules — and four companion projects: a Kubernetes operator, Terraform provider, Pulumi provider, and a CLI for packing signed WASM plugin artefacts.

Quick Start

Run with Docker

docker pull ghcr.io/dimensigon/hdb-heliosdb-proxy:0.4.0

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

Open the built-in admin web UI at http://localhost:9090/.

Configure

Minimal proxy.toml:

[server]
listen = "0.0.0.0:5432"
admin_listen = "0.0.0.0:9090"

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

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

[plugins]
enabled    = true
plugin_dir = "/var/lib/heliosproxy/plugins"
trust_root = "/etc/heliosproxy/plugin-keys"  # optional Ed25519 trust root

See Configuration for the full reference.

Topology

                  ┌─────────────┐
                  │ HeliosProxy │  ← WASM plugins, replay engine,
                  │   v0.4.0    │    upgrade orchestrator, admin UI
                  └──────┬──────┘
                         │  PostgreSQL wire protocol
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐      ┌─────────┐      ┌─────────┐
   │ Primary │      │ Standby │      │ Replica │
   │ (PG 17) │      │ (PG 17) │      │ (PG 17) │
   └─────────┘      └─────────┘      └─────────┘

Documentation Structure

Architecture — System design, request lifecycle, hook points
Configuration — Full proxy.toml reference
Feature Flags — Cargo features and module activation
Admin API — REST endpoints (topology, plugins, anomalies, edge, chaos, shadow, replay)
Topology Providers — Backend discovery (PostgreSQL polling, HeliosDB native)
Transaction Replay — Journal-backed replay, shadow execution
Deployment Guides — Docker, Kubernetes, standalone

Source Repositories

Repository	Role	License
`HDB-HeliosDB-Proxy`	Core proxy (this is where most files live)	AGPL-3.0
`HDB-HeliosDB-Proxy-Plugins`	First-party WASM plugins + `helios-plugin` CLI	AGPL-3.0
`HDB-HeliosDB-Proxy-Operator`	Kubernetes operator	AGPL-3.0
`terraform-provider-HDB-HeliosDB-Proxy`	Terraform provider	AGPL-3.0
`pulumi-HDB-HeliosDB-Proxy`	Pulumi provider	AGPL-3.0

Container image: ghcr.io/dimensigon/hdb-heliosdb-proxy:0.4.0 (lowercase due to GHCR convention).

What’s New

v0.4.0 — From Connection Router to Programmable Data-Plane — 22 new modules, real WASM runtime, time-travel replay, PG upgrade orchestrator, admin UI
v0.3.1 — Hot-path Performance & Correctness — 28-37% faster pool checkout, lock-free metrics, zero-allocation parsing

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 TWR
examples/multi-tenant — per-tenant pool isolation