---
title: "HeliosProxy Documentation"
---

# HeliosProxy Documentation

**Programmable Postgres Data-Plane**

[![License](https://img.shields.io/badge/license-Apache_2.0-green.svg)](https://github.com/HeliosDatabase/HeliosDB-Proxy/blob/main/LICENSE)
[![Container](https://img.shields.io/badge/container-ghcr.io%2Fheliosdatabase%2Fhdb--heliosdb--proxy-blue.svg)](https://ghcr.io/heliosdatabase/hdb-heliosdb-proxy)

---

## 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](/docs/proxy/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

```bash
# 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](/docs/proxy/deployment/docker/).

### Install from crates.io

```bash
cargo install heliosdb-proxy
```

The minimum supported Rust version is **1.86**.

### Configure

Minimal `proxy.toml`:

```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](/docs/proxy/configuration/) for the full reference, and the repo's [`config/`](https://github.com/HeliosDatabase/HeliosDB-Proxy/tree/main/config) directory for complete example files.

## Topology

```text
                  ┌─────────────┐
                  │ 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](/docs/proxy/architecture/)** — System design, request lifecycle, hook points
- **[Configuration](/docs/proxy/configuration/)** — Full `proxy.toml` reference, including `[limits]`, `[anomaly]`, `[cache]`, `[auth]`, `[tls]` and `[[hba]]`
- **[Feature Flags](/docs/proxy/feature-flags/)** — Cargo features and module activation
- **[Admin API](/docs/proxy/admin-api/)** — REST endpoints (topology, plugins, plugin KV, anomalies, edge, chaos, migration, replay, metrics)
- **[Topology Providers](/docs/proxy/topology-providers/)** — Backend discovery and write authority (static roles, PostgreSQL polling with the timeline rule, Patroni)
- **[Transaction Replay](/docs/proxy/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](/docs/proxy/deployment/docker/)** — Docker, Kubernetes, standalone
- **[Release History](/docs/proxy/releases/)** — Changes by release, upgrade notes and the earlier release notes

## Source Repositories

| Repository | Role | License |
|---|---|---|
| [`HeliosDB-Proxy`](https://github.com/HeliosDatabase/HeliosDB-Proxy) | Core proxy (this is where most files live) | Apache-2.0 |
| [`HeliosDB-Proxy-Plugins`](https://github.com/HeliosDatabase/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](/docs/proxy/releases/) page. The repository
[CHANGELOG](https://github.com/HeliosDatabase/HeliosDB-Proxy/blob/main/CHANGELOG.md) is the
complete record.

## Examples & Demos

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

- [`examples/postgres-cluster`](https://github.com/HeliosDatabase/HeliosDB-Proxy/tree/main/examples/postgres-cluster) — full PG-cluster + proxy compose
- [`examples/failover-demo`](https://github.com/HeliosDatabase/HeliosDB-Proxy/tree/main/examples/failover-demo) — manual failover with Transaction Replay
- [`examples/multi-tenant`](https://github.com/HeliosDatabase/HeliosDB-Proxy/tree/main/examples/multi-tenant) — per-tenant pool isolation

The platform-tier feature demos remain in the repository's [`demos/`](https://github.com/HeliosDatabase/HeliosDB-Proxy/tree/main/demos) directory and are catalogued under [Demos](/docs/proxy/demos/).