April 25, 2026

From Connection Router to Programmable Data-Plane

This is the largest release in HeliosProxy's history. The proxy is no longer a router with feature flags — it is a programmable data-plane with a real WASM runtime, signed plugins distributed via OCI, time-travel replay over a transaction journal, a zero-downtime PostgreSQL major-version upgrade orchestrator, and a built-in admin web console. All 24 connection-routing feature modules remain.

Programmable

Real WASM Plugin Runtime

Wasmtime executes signed plugins inside the proxy. Five hook points — Authenticate, Route, PreQuery, PostQuery, Validate — each can rewrite, augment, or block. RouteResult::Block denies queries before they hit a backend.

Signed & Distributed

Ed25519 + OCI Artefacts

Plugin signature verification at load time. SignatureVerifier wired into the runtime config. Distribution via .tar.gz OCI artefacts pulled from any OCI registry — sign, push, deploy.

Time-Travel

Replay Engine over the Journal

Replay any window of historical traffic against the current cluster, a standby, or a candidate. Per-call credential overrides; admin /api/replay; built-in UI form. TransactionJournal is auto-attached in ServerState.

Upgrade Orchestrator

Zero-Downtime PG Major Versions

Real SQL stage bodies execute on a tick schedule. Shadow-execution comparator runs traffic against both the old and new backend, diffing results before the cut. The hardest operational task on Postgres, orchestrated by the proxy.

Real Backend

No More Simulated Failover

Real PG connection pool, pg_is_in_recovery() polling, pg_promote + WAL probe sync-wait, real statement replay against the replacement primary, and simple-protocol SET state restored transactionally. Cursors, PREPAREd statements and temp tables are not restored — see the refusal list below.

Operator UX

Built-in Admin Console

Static admin web UI at /. Topology, plugins, chaos mode, shadow execution, time-travel replay — all first-class panels. No separate admin tool to deploy or secure.

License Update

HeliosProxy is licensed under Apache 2.0. Permissive, OSI-approved, and aligned with HeliosDB Nano — use it freely in commercial, managed-service, and proprietary deployments without copyleft obligations.

Programmable Data-Plane

WASM Plugins, Real This Time

Plugins are not configuration. They are real WebAssembly modules executing inside the proxy with sandboxed wasmtime, fuel-metered execution, and bounded memory. Five hook points cover authentication, routing, query lifecycle, and validation. Authoring is one Rust crate; deployment is one signed OCI artefact.

Five hook points — Authenticate, Route, PreQuery, PostQuery, Validate. Each can short-circuit, rewrite, deny, or augment.
Ed25519 signature verification — SignatureVerifier enforces signatures at load time. cargo helios-plugin sign is the publisher path.
OCI distribution — .tar.gz artefacts pulled from any OCI registry; the loader handles unpacking and signature verification end-to-end.
Host imports — KV namespace, env.sha256_hex. Plugins can do real work without escaping the sandbox.
Block routing — RouteResult::Block denies a query at the routing stage and returns a structured reason to the client.
Cached responses as PG wire frames — plugins can synthesise PG protocol frames directly when serving from cache.

Plugin lifecycle

# 1. Author the plugin (Rust crate, compile to wasm32-wasi)
cargo build --release --target wasm32-wasi

# 2. Sign with your Ed25519 key
cargo helios-plugin sign \
  --key   ./signing.key \
  --input target/wasm32-wasi/release/auth_plugin.wasm

# 3. Push to any OCI registry
oras push registry.example.com/my-org/auth-plugin:v1 \
  ./auth_plugin.wasm.tar.gz

# 4. Reference in heliosproxy.toml
[[plugins]]
name      = "auth"
source    = "oci://registry.example.com/my-org/auth-plugin:v1"
hooks     = ["Authenticate", "PreQuery"]
verify_with = "./trusted-keys.toml"

High Availability · 1.7.0

Transaction Replay — In-Session Failover

Transaction Replay keeps client sessions alive through a primary failure: sessions re-home and restore state, an interrupted read re-runs when it is provably side-effect-free, and opt-in transaction mode replays uncommitted work on the new primary — verifying every replayed result against what the client already saw.

No cargo feature, no application change. In-session recovery is core — any PostgreSQL-wire client, any PG-wire backend. The ha-tr feature is a separate thing: the write journal and the operator-driven /api/replay and /api/shadow endpoints.

tr_mode selects how much the proxy does on your behalf when the primary fails. Each level includes the one before it:

none — the client gets a proper PostgreSQL error (SQLSTATE 57P01) and the connection closes.
session (default) — the connection stays alive; the proxy re-homes it to the new primary and replays the session's tracked SET/RESET state. The interrupted statement returns one error (57P01 if it never reached the old primary, 08007 if its outcome is unknown); not-yet-delivered autocommit statements are re-executed transparently.
select — additionally re-runs an interrupted read, but only when every function it calls is provably side-effect-free — a PostgreSQL built-in on the proxy's allowlist, or a name you added to tr_read_functions. A read calling a user-defined function, nextval, pg_notify, set_config or an advisory lock is opaque: it returns 08007 and is never run a second time.
transaction (opt-in) — additionally replays the uncommitted transaction from its BEGIN on the new primary. Replay is verified: each statement's original response frames were digested as the client saw them, the replacement backend's responses are digested the same way, and any divergence rolls the replay back with 40001 rather than continuing on top of rows the client never observed.

Session state. SET/RESET tracking is transactional and savepoint-scoped, mirroring PostgreSQL: a SET inside a transaction takes effect for restore only if that transaction commits, and ROLLBACK TO SAVEPOINT discards the ones issued after the savepoint. It covers simple-protocol statements only — extended-protocol SETs as sent by JDBC, SQL-level PREPARE, session temp tables and open cursors are not restored.

One deadline. Since 1.7.0 write_timeout_secs bounds the entire recovery — waiting for a healthy primary, connect and auth, session-state restore, replay and re-execution — instead of each phase carrying its own timeout that could add up past the configured value. Failing over onto password-protected backends needs the proxy as the auth boundary ([auth] mode = "scram").

Verified live against PostgreSQL 18.4: a 77-check failover battery across all four modes, plus a 7-case commit-outcome suite and a 13-case streaming suite that the pre-fix binary failed 4 and 12 of respectively. Full behaviour reference →

proxy.toml

# In-session failover — core, no cargo feature
tr_enabled = true
tr_mode = "session"     # none | session | select | transaction
write_timeout_secs = 30 # one deadline for the whole recovery
tr_read_functions = []  # extra provably-pure functions

[auth]
mode = "scram"          # proxy is the auth boundary

[limits]
tr_max_replay_statements = 1000
tr_max_replay_bytes = 16777216
tr_max_session_set_statements = 256
tr_max_observation_bytes = 1048576  # replay-verification digest
max_backend_frame_bytes = 104857600 # bounds one backend frame
backend_response_timeout_secs = 0   # 0 = off; bounds a slow drip

# Prometheus (/metrics)
# tr_failovers_total
# tr_statements_reexecuted_total
# tr_transactions_replayed_total
# tr_replay_failures_total
# tr_unknown_outcome_errors_total

Incident Response

Time-Travel Replay

Every transaction the proxy sees is journalled. Replay any window of historical traffic against the current cluster, a standby, or a brand-new candidate — with optional per-call credential overrides for security validation and migration rehearsal. The shadow-execution comparator runs the same traffic against two backends side-by-side and diffs the result, catching divergence before a cut.

Journal-backed — TransactionJournal auto-attached to ServerState; no separate storage to provision.
Programmatic + UI — POST /api/replay for automation; the admin UI ships a built-in form for operator-driven replays.
Per-call credential override — replay traffic that ran as user A as user B. Useful for security validation and migration rehearsal.
Shadow-execution comparator — run identical traffic against two backends and diff the results. First-class incident-prevention tool during version cuts.

Replay API

# Replay last hour against a candidate node
curl -X POST http://proxy:9090/api/replay \
  -H "Content-Type: application/json" \
  -d '{
    "from":      "2026-04-26T10:00:00Z",
    "to":        "2026-04-26T11:00:00Z",
    "target":    "candidate-pg17",
    "as_user":   "audit_replay",
    "shadow":    true,
    "diff_mode": "rows"
  }'

# Returns: replay_id, statements_replayed,
# diff_count, divergent_query_ids[]

Migration Wedge

Zero-Downtime PostgreSQL Major-Version Upgrades

The hardest operational task on Postgres — major-version upgrades — is now coordinated by the proxy. Real SQL stage bodies execute on a tick schedule against both the old and new instances. The chaos-mode admin endpoint injects controlled failures during rehearsal. The shadow-execution comparator validates that the new backend produces equivalent results before traffic moves.

Stage-driven — declarative stages execute as the upgrade progresses; tick-scheduled SQL bodies do real work, not heartbeat checks.
Chaos rehearsal — admin /api/chaos + UI panel inject failure scenarios so you find issues in pre-prod, not in the cut window.
Shadow validation — T3.4 comparator runs the same query against PG 12 and PG 17 and reports diff. Cut only when diff is empty over a window you specify.
PG-12-EOL ready — this is the wedge for the upcoming Postgres EOL wave. Plan, rehearse, cut, and rollback — all coordinated from the proxy.

heliosproxy.toml

[upgrade]
enabled          = true
from_backend     = "pg12-prod"
to_backend       = "pg17-candidate"
shadow_window    = "24h"
cut_threshold    = 0  # max diff rows

[[upgrade.stages]]
name      = "backfill"
tick      = "30s"
sql       = """
INSERT INTO pg17.events
SELECT * FROM pg12.events
WHERE id > (SELECT COALESCE(MAX(id), 0) FROM pg17.events)
LIMIT 10000
"""

[[upgrade.stages]]
name      = "verify"
tick      = "5m"
sql       = "SELECT COUNT(*) FROM pg17.events"

Operator UX

Built-in Admin Console

A static admin web UI ships with the proxy at the root path. No separate admin service to deploy, no extra service to secure, no second auth model to keep in sync. Topology, plugins, chaos mode, shadow execution, and time-travel replay are all first-class panels.

Topology panel — live view of every backend, role, lag, and health.
Plugins panel — list loaded plugins, signature status, hook bindings; toggle and reload.
Chaos mode panel — inject latency, errors, partitions for rehearsals.
Shadow execution panel — configure which traffic shadows where, and inspect diffs.
Time-travel replay form — pick a window, target, credential override, and submit.

Auth: shares the proxy's existing admin auth model (JWT or API key). The UI is static HTML/JS served from the same binary — no Node.js, no build step, no second container.

Admin endpoints

# Topology
GET    /api/topology
GET    /api/health

# Plugins
GET    /plugins
POST   /plugins/{id}/reload
POST   /plugins/{id}/disable

# Chaos mode
POST   /api/chaos
GET    /api/chaos/active

# Time-travel replay
POST   /api/replay
GET    /api/replay/{id}

# Shadow execution
POST   /api/shadow/start
GET    /api/shadow/{id}/diff

April 22, 2026

Hot-Path Performance & Correctness

Earlier this month: pool-checkout 28–37% faster, 3.1× faster metrics reads, zero-allocation protocol parsing, concurrent L1 cache hits. Still in the latest release. Full release notes →

Connection Pool

Per-Node Checkout, No Global Lock

Idle-connection pop and semaphore acquire happen outside the map lock. Per-node state is held behind a cheap cloneable Arc<Semaphore>, so concurrent checkouts to different backends no longer contend.

Pool Metrics

Lock-Free Atomic Counters

Acquires, timeouts, connections created/closed, recycles, and validation failures are atomic. Reading the full pool.metrics() snapshot is sub-15 ns and never contends with checkouts.

PostgreSQL Parser

Zero-Allocation Parameter Parse

Prepared-statement parameter values are handled as reference-counted slices into the original protocol buffer — no per-parameter heap allocation during parse. C-string reads use a single scan rather than incremental buffer growth.

L1 Hot Cache

Concurrent Hits, Read-Lock Only

Cache hits take a read lock and bump an atomic per-entry access counter, so many threads can hit the same cached query in parallel without serialising. Covered by a 16-thread × 500-iteration regression test.

Benchmark: Previous → Latest release

Benchmark	Previous	Latest	Change
`pool/acquire_release/single`	471.81 ns	329.83 ns	−30%
`pool/throughput/sequential_acquire/1`	490.36 ns	353.88 ns	−28%
`pool/throughput/sequential_acquire/10`	5.354 µs	3.351 µs	−37%
`pool/throughput/sequential_acquire/50`	25.36 µs	16.95 µs	−33%
`pool/metrics/read_metrics`	35.90 ns	11.51 ns	−68% (3.1×)

Method: cargo bench --bench pooling -- --quick, same machine, single-threaded, criterion quick mode. Directional indicator of request-path cost — the pool is one component; full-proxy QPS depends on backend, workload, and network.

Why HeliosProxy?

HeliosProxy transforms HeliosDB into a production-ready platform with connection pooling, intelligent caching, rate limiting, and enterprise resilience — all in one component.

Challenge	Without Proxy	With HeliosProxy
Connection limits	App manages pools	Automatic pooling
Query caching	Manual Redis / Memcached	Built-in 3-tier cache
Rate limiting	External service	Native support
Multi-tenancy routing	App logic	Automatic routing
Circuit breaking	Manual implementation	Built-in resilience
GraphQL API	Separate gateway	Auto-generated
Authentication	Custom middleware	JWT, OAuth, LDAP, API Keys

Connection Management

Connection Pooling

Three modes to match your workload. Achieve up to 100:1 connection multiplexing, turning 5,000 client connections into just 50 server connections. Eliminate connection storms, reduce database load, and scale your application layer independently.

Session Mode — Connections assigned for entire client session. Best for long-running connections and connection-level state.
Transaction Mode — Connections returned to pool after each transaction. Best for web applications and microservices. Achieves 10:1 multiplexing.
Statement Mode — Connections returned after each statement. Best for simple queries and serverless functions. Achieves 100:1 multiplexing.

heliosproxy.toml

# Session mode: 1:1 mapping
[pool]
mode = "session"
max_connections = 500

# Transaction mode: 10:1 multiplexing
[pool]
mode = "transaction"
max_connections = 1000
server_connections = 100

# Statement mode: 100:1 multiplexing
[pool]
mode = "statement"
max_connections = 5000
server_connections = 50

Helios-DistribCache

Multi-Tier Caching

Intelligent 3-tier distributed caching system that automatically promotes hot data and evicts cold entries. Reduce database load by up to 95% with sub-millisecond cache hits.

L1: Hot Cache — Per-connection local memory. Sub-millisecond latency for the hottest queries. LRU eviction with configurable TTL. Hits take a read lock only and bump an atomic access counter, so many threads can hit the same key in parallel without serialising.
L2: Warm Cache — Shared across all proxy nodes via Redis cluster. 1-5ms latency. Consistent hashing for even distribution.
L3: Semantic Cache — AI-powered cache that matches semantically similar queries. Uses embedding similarity (threshold 0.95) to return cached results for paraphrased queries.

Automatic cache invalidation on writes. Configurable exclusion patterns for INSERT, UPDATE, and DELETE statements.

SQL + Config

-- This query hits L1 cache (sub-ms)
SELECT * FROM users
WHERE id = 42;

-- Similar query hits L3 semantic cache
SELECT * FROM users
WHERE user_id = 42;

# Cache configuration
[cache]
enabled = true

[cache.l1]
size = "1GB"
ttl = "60s"
eviction = "lru"

[cache.l2]
type = "redis"
hosts = ["redis-1:6379", "redis-2:6379"]
ttl = "5m"

[cache.semantic]
enabled = true
similarity_threshold = 0.95

API Layer

GraphQL Gateway

Automatic GraphQL schema generation from your database tables. No code generation step, no manual schema definitions — HeliosProxy introspects your database and generates a full GraphQL API in real time.

Auto-generated queries, mutations, and subscriptions from SQL schema
Relationship resolution from foreign keys
Filtering, sorting, pagination built-in
Configurable max query depth to prevent abuse
Introspection toggle for production safety
Real-time subscriptions via WebSocket

GraphQL

# Auto-generated from SQL schema
query {
  users(where: { active: true }, limit: 10) {
    id
    email
    orders(orderBy: { createdAt: DESC }) {
      id
      total
      items {
        product_name
        quantity
      }
    }
  }
}

# Enable in config:
# [graphql]
# enabled = true
# endpoint = "/graphql"
# introspection = true
# max_depth = 10

Extensibility

WASM Plugins

Extend HeliosProxy with custom WebAssembly plugins. Write your logic in Rust, Go, or any language that compiles to WASM, and inject it into the query pipeline at any hook point.

Query rewriting — transform queries before execution
Result filtering — redact or transform results
Custom authentication — integrate with any identity provider
Audit logging — capture events to external systems
Sandboxed execution — plugins cannot crash the proxy
Hot-reload — deploy plugins without proxy restart

Rust (WASM Plugin)

use wasm_bindgen::prelude::*;

// Custom query rewriting plugin
#[wasm_bindgen]
pub fn rewrite_query(
    query: &str,
    context: &Context
) -> String {
    // Add tenant filter to all queries
    if !query.contains("tenant_id") {
        query.replace(
            "WHERE",
            &format!(
                "WHERE tenant_id = {} AND",
                context.tenant_id
            )
        )
    } else {
        query.to_string()
    }
}

# Plugin configuration
# [plugins.wasm]
# name = "tenant-filter"
# path = "/plugins/tenant_filter.wasm"
# hook = "query_rewrite"

Smart Routing

Intelligent Query Routing

HeliosProxy automatically classifies and routes queries to the optimal backend. Lag-aware read replicas, circuit breaker protection, and workload-based routing ensure every query hits the best target.

Lag-aware routing — Monitors replica lag and only routes reads to replicas within acceptable thresholds
Circuit breaker — Automatically detects failing backends and reroutes traffic. CLOSED to OPEN after 5 failures, automatic recovery after 30s
Workload classification — OLTP queries go to primary (optimized for latency), OLAP queries go to analytics replicas, vector queries to vector-optimized nodes
Data temperature — Route hot data (last 7 days) to primary, warm data to replicas, cold data to archive storage

heliosproxy.toml

# Workload-based routing
[routing]
schema_aware = true

[routing.workload]
enabled = true

# OLTP queries -> primary
oltp_patterns = [
    "SELECT * FROM users WHERE id",
    "INSERT INTO orders"
]
oltp_target = "primary"

# OLAP queries -> analytics replica
olap_patterns = [
    "SELECT.*GROUP BY",
    "SELECT.*ORDER BY.*LIMIT"
]
olap_target = "analytics"

# Vector queries -> vector node
vector_patterns = [
    "ORDER BY.*<=>",
    "embedding.*<->"
]
vector_target = "vector-node"

# Circuit breaker
[circuit_breaker]
enabled = true
failure_threshold = 5
reset_timeout = "30s"
half_open_requests = 3

Query Intelligence

Query Rewriting & Optimization

HeliosProxy inspects and optimizes queries before they reach the database. Automatic rewriting improves performance without any application code changes.

Automatic tenant injection — Transparently adds tenant filters to every query for multi-tenant applications
Query normalization — Canonicalizes queries for better cache hit rates
Parameter binding — Converts inline values to parameterized queries for plan reuse
Read/write splitting — Automatically routes SELECT queries to read replicas
Query cost estimation — Pre-estimates query cost and rejects expensive queries before execution
AI workload detection — Automatically detects RAG, conversation context, and embedding queries for optimized handling

heliosproxy.toml

# AI workload optimization
[ai_cache]
enabled = true

# Conversation context cache
conversation_context_ttl = "30m"
conversation_context_size = "512MB"

# RAG chunk cache
rag_chunk_cache_size = "2GB"
rag_chunk_ttl = "1h"

# Semantic query cache
semantic_cache_enabled = true
similarity_threshold = 0.95

# Query cache control
[cache.query]
enabled = true
max_result_size = "10MB"
exclude_patterns = [
    "INSERT",
    "UPDATE",
    "DELETE"
]

Security

Authentication Proxy

Centralized authentication before database access. Support for JWT, OAuth 2.0, LDAP, and API keys — all validated at the proxy layer before any query reaches the database.

JWT validation — Verify tokens against JWKS endpoints. Extract tenant ID, roles, and permissions from claims.
OAuth 2.0 — Full OAuth flow support with token refresh and scope validation
LDAP integration — Authenticate against Active Directory or OpenLDAP
API key management — Issue, rotate, and revoke API keys with per-key rate limits
Role mapping — Map external identity claims to database roles automatically

heliosproxy.toml

[auth]
enabled = true

# JWT validation
[auth.jwt]
enabled = true
issuer = "https://auth.example.com"
audience = "heliosdb"
jwks_url = "https://auth.example.com/.well-known/jwks.json"

# Extract tenant from JWT claims
tenant_claim = "org_id"
role_claim = "db_role"

# API key validation
[auth.api_key]
enabled = true
header = "X-API-Key"

# LDAP integration
[auth.ldap]
enabled = true
server = "ldap://ldap.example.com:389"
base_dn = "dc=example,dc=com"

Isolation

Multi-Tenancy

Flexible tenant isolation strategies to match your architecture. From shared-database with Row-Level Security to dedicated databases per tenant — HeliosProxy handles routing, resource limits, and isolation transparently.

Schema-based isolation — Each tenant gets a dedicated schema within a shared database
RLS-based isolation — Shared tables with automatic Row-Level Security tenant filters
Database-based isolation — Dedicated database per tenant with independent connection pools
Per-tenant resource limits — Configurable pool size, cache allocation, and rate limits per tenant
Tenant routing — Automatically route by HTTP header (X-Tenant-ID) or JWT claim

heliosproxy.toml

[tenancy]
enabled = true
tenant_header = "X-Tenant-ID"
default_tenant = "public"

# Enterprise tenant: dedicated DB
[[tenancy.tenant]]
id = "enterprise-1"
database = "enterprise_1"
pool_size = 100
cache_size = "2GB"

# Startup tenant: shared DB
[[tenancy.tenant]]
id = "startup-tier"
database = "shared"
pool_size = 10
cache_size = "256MB"
rate_limit_qps = 100

Observability

Query Analytics

Track and analyze every query pattern flowing through HeliosProxy. Identify slow queries, monitor cache efficiency, and understand your workload — all with built-in analytics.

Slow query logging — Automatically capture queries exceeding configurable thresholds (default: 100ms)
Query pattern analysis — Group normalized queries to identify the most frequent and expensive patterns
Cache efficiency metrics — Real-time cache hit/miss rates across all three tiers
Lock-free pool counters — Acquires, timeouts, connections created/closed, recycles, and validation failures are atomic. pool.metrics() snapshots read in sub-15 ns and never contend with checkouts.
Configurable sampling — Sample 10% of queries in production for minimal overhead
Real-time dashboard — Query built-in analytics tables via SQL for integration with any monitoring tool

SQL

-- Top 20 slowest queries
SELECT query_pattern,
       avg_duration,
       call_count
FROM heliosproxy_query_stats
ORDER BY avg_duration DESC
LIMIT 20;

-- Most frequent queries + cache hits
SELECT query_pattern,
       call_count,
       cache_hit_rate
FROM heliosproxy_query_stats
ORDER BY call_count DESC
LIMIT 20;

-- Overall cache efficiency
SELECT
    SUM(cache_hits) AS hits,
    SUM(cache_misses) AS misses,
    ROUND(
        SUM(cache_hits)::float /
        (SUM(cache_hits) + SUM(cache_misses)),
        3
    ) AS hit_rate
FROM heliosproxy_cache_stats;

Protection

Rate Limiting

Protect your database from overload with granular rate limiting at every level. Global limits, per-tenant quotas, per-user throttling, and per-query cost limits — all enforced at the proxy layer.

Global limits — Cap total queries per second and concurrent connections across all tenants
Per-tenant limits — Different QPS and connection quotas for each pricing tier
Burst allowance — Allow short traffic bursts above the sustained rate limit
Graceful degradation — Returns retry-after headers for clients to implement exponential backoff
Real-time counters — Monitor rate limit consumption via analytics tables

heliosproxy.toml + Python

[rate_limit]
enabled = true

# Global limits
global_qps = 10000
global_connections = 5000

# Enterprise customer
[[rate_limit.tenant]]
id = "enterprise-customer"
qps = 2000
connections = 500

# Free tier
[[rate_limit.tenant]]
id = "free-tier"
qps = 100
connections = 10
burst = 20

# Client-side handling
try:
    cursor.execute("SELECT * FROM users")
except HeliosError as e:
    if e.code == "RATE_LIMIT_EXCEEDED":
        time.sleep(e.retry_after)

High Availability · ha-tr

The Write Journal & Operator Replay

In-session recovery above needs no build flag. The optional ha-tr cargo feature adds something different — a write journal and the operator tooling that reads it. None of it sits on the path a live client takes through a failover.

Write journal — a post-response, in-memory log of write SQL, bounded by code constants: 10,000 entries and 64 MiB per transaction, 50,000 journals globally, oldest evicted first. Not persisted.
Time-travel replay — POST /api/replay re-executes a [from, to] window of that journal against a target backend and returns statements_replayed, failures and elapsed_ms. "Re-run yesterday 10:00–11:00 against staging."
Shadow execution — POST /api/shadow runs a query against a source and a shadow backend in parallel and diffs the results: upgrade validation, migration canaries, replica-drift detection.
Failover library — FailoverController, PrimaryTracker and SwitchoverBuffer as embeddable components, with promotion policy, WAL-LSN sync-wait and planned-switchover buffering.
Savepoint-aware — the journal records savepoints and truncates on ROLLBACK TO, so a replay reflects the post-rollback statement set.
Stated plainly — this journal is in-memory and best-effort, and the live hook records SQL text. Hardening it into a durable, ordered, recovery-grade log is the next item in this series.

build + admin API

# Opt in at build time
cargo build --release \
  --features "pool-modes,ha-tr"

# Replay a journal window against staging
curl -X POST localhost:9090/api/replay \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data @replay-window.json

# => {"statements_replayed": 4812,
#     "failures": 0,
#     "elapsed_ms": 9134}

# Diff one query across two backends
curl -X POST localhost:9090/api/shadow \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data @shadow-request.json

# Built without the feature, the route still
# answers — and says so:
#   503 {"error":
#     "ha-tr feature not compiled in"}
# In-session failover is unaffected.

High Availability · 1.7.0

What It Refuses To Do

Transparent recovery is the goal; a clear error is the fallback; a wrong answer is never acceptable. These refusals are the feature. Each one carries a specific SQLSTATE rather than a silent guess.

An unknown COMMIT outcome is never retried — the client gets 08007 and guidance to verify. This covers COMMIT, END, PREPARE TRANSACTION and COMMIT PREPARED.
A response already partly delivered closes the session — rather than append a second execution's rows to the first one's output.
Snapshot-pinned transactions are not replayed — SERIALIZABLE or REPEATABLE READ, whether set on BEGIN, via SET TRANSACTION, or inherited from default_transaction_isolation. No replacement backend can reproduce that snapshot.
Unverifiably large responses are not replayed — a response beyond [limits] tr_max_observation_bytes has no digest to verify against, so its transaction is marked non-replayable.
Exceeding the tracked session-state cap refuses the failover — 08006, rather than re-homing a session with half its settings.
Divergence at replay-verification time returns 40001 — the replay rolls back instead of continuing on rows the client never saw.
An opaque read is never run twice — anything calling outside the side-effect-free set returns 08007.
A COPY in progress at the fault — 08006, connection closed.

Verification catches divergent results; it does not create determinism. Replay will not make now(), random() or a RETURNING serial reproduce their first values — which is why transaction mode is opt-in.

client-visible SQLSTATEs

-- The backend died mid-transaction.
-- Recovery succeeded, verified:
COMMIT;
-- (no error; a slow query, not a drop)

-- Replayed rows did not match what
-- this client already saw:
-- ERROR:  40001 serialization_failure
--   replay verification failed;
--   transaction rolled back

-- The COMMIT may or may not have landed:
-- ERROR:  08007
--   transaction_resolution_unknown
--   verify before retrying

-- Session state could not be restored:
-- ERROR:  08006 connection_failure

-- Never restored across a failover:
--   SQL-level PREPAREd statements
--   session temp tables
--   open cursors
--   advisory locks
--   extended-protocol SETs (JDBC)

High Availability · 1.7.0

Session State Across a Failover

Re-homing a session means opening a fresh backend connection, so session state has to be rebuilt on the new primary. HeliosProxy restores the part it can track correctly, and is explicit about the rest.

Restored: simple-protocol SET/RESET — tracked per session and replayed in order onto the replacement backend. Covers timezone, search_path, client_encoding, datestyle, application_name and arbitrary custom variables.
Transactional, since 1.7.0 — a SET inside a transaction takes effect for restore only when that transaction commits; ROLLBACK discards it. RESET, RESET ALL and DISCARD ALL inside a transaction are deferred to commit, so a rolled-back RESET ALL no longer wipes the restore set.
Savepoint-scoped — ROLLBACK TO SAVEPOINT discards the SETs issued after that savepoint; RELEASE keeps them.
Keyed by variable name — repeating a SET reuses its slot instead of consuming another. [limits] tr_max_session_set_statements (default 256) counts distinct variables; exceeding it refuses the failover with 08006.
Not restored — SQL-level PREPAREd statements, session temp tables, open cursors and advisory locks. Applications depending on that state surviving a failover still need application-level coordination.
Not tracked — SETs issued through the extended query protocol, as most JDBC drivers send them. SET LOCAL, SET TRANSACTION and SET CONSTRAINTS are transaction-scoped by definition and never tracked.

SQL

-- Tracked as the session runs
SET timezone TO 'America/New_York';
SET search_path TO myapp, public;
SET app.tenant_id TO '42';

BEGIN;
  SET statement_timeout TO '5s';
  SAVEPOINT sp1;
  SET work_mem TO '256MB';
  ROLLBACK TO sp1;   -- work_mem dropped
COMMIT;              -- statement_timeout kept

-- Primary dies. On the new backend the
-- proxy replays exactly the surviving set:
--   SET timezone TO 'America/New_York'
--   SET search_path TO myapp, public
--   SET app.tenant_id TO '42'
--   SET statement_timeout TO '5s'

-- Had that COMMIT been a ROLLBACK,
-- statement_timeout would not be restored.

-- Over 256 distinct variables, the
-- failover is refused outright:
--   ERROR: 08006 connection_failure

Application Continuity

Transparent Write Routing (TWR)

Connect to any node — primary or standby — and HeliosProxy automatically routes write operations to the current primary. Applications never need to track topology changes, enabling true connect-anywhere simplicity with zero client-side routing logic.

Automatic write detection — Intercepts INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, and COPY statements, forwarding them to the primary node transparently
Three sync modes — Sync (wait for standby confirmation), SemiSync (wait for WAL flush), or Async (fire-and-forget) per-connection tuning
Connection pooling — Maintains a dedicated forwarding pool to the primary with configurable size, timeouts, and health checks
Read-after-write consistency — Sync mode guarantees subsequent reads on the standby reflect the forwarded write, eliminating stale reads
Topology-aware failover — Automatically detects primary changes during failover and re-routes writes to the new primary without client reconnection
Full PostgreSQL protocol — Supports extended query protocol, prepared statements, and parameterized queries through the forwarding path

heliosproxy.toml + SQL

# Transparent Write Routing
[transparent_write_routing]
enabled = true
sync_mode = "sync"
forward_timeout_ms = 5000

[transparent_write_routing.pool]
max_connections = 50
idle_timeout_ms = 60000
health_check_interval_ms = 5000

-- App connects to ANY node (standby)
-- Reads stay local, writes auto-route
SELECT * FROM orders
  WHERE user_id = 42;
-- → executes on standby (local)

INSERT INTO orders (user_id, total)
  VALUES (42, 149.99);
-- → auto-forwarded to primary
-- → sync: confirmed on standby

Complete Platform

46 Feature Modules
In One Component

24 connection-routing modules + 22 platform modules (plugin-host extensions, admin surface, first-party plugins, companion projects). Each module is independently activated via a compile-time feature flag. Enable only what your deployment requires — no unused code ships in your binary.

1. Connection Pooling

Session, Transaction, Statement modes with up to 100:1 multiplexing and prepared statement forwarding.

2. Load Balancer

Round-robin, least-connections, or latency-based distribution. Automatic read/write splitting.

3. Health Checker

Configurable health-check queries, failure thresholds, and automatic node removal/recovery.

4. Request Pipeline

PostgreSQL extended query protocol pipelining. Batches Parse, Bind, Execute to reduce round trips. Parameter values parsed as zero-copy slices into the protocol buffer.

5. Batch Operations

Auto-coalesces individual INSERTs into multi-row batches for higher write throughput.

6. Failover Controller

Automatic failover with promotion policies. Prefers sync standbys, ranks by replication lag.

7. Transaction Replay

Core, no build flag. Replays the uncommitted transaction on the new primary and verifies every replayed response against what the client already saw.

8. Session State Restore

Replays simple-protocol SET/RESET onto the replacement backend, transactionally and savepoint-scoped. PREPARE, temp tables and cursors are not restored.

9. Replay Verification

Digests each response as the client saw it and re-checks it on replay. Divergence rolls back with SQLSTATE 40001 instead of continuing on unseen rows.

10. Switchover Buffer

Buffers incoming queries during failover and drains to the new primary. Increased latency, not errors.

11. Primary Tracker

Pluggable topology discovery: PostgreSQL polling, HeliosDB native events, or manual via Admin API.

12. Transaction Journal

Write-ahead journal for in-flight transactions with statement-level granularity and parameter capture.

13. Query Cache

Three-tier result cache: L1 hot (sub-μs), L2 warm (TTL-based), L3 semantic (normalized matching).

14. Query Routing Hints

Embed routing directives in SQL comments: /*+ route=primary */, /*+ route=nearest */.

15. Lag-Aware Routing

Routes reads to replicas within a configurable lag threshold. Includes read-your-writes consistency.

16. Query Rewriter

Rule-based SQL transformations: add hints, inject filters, redirect tables, enforce naming conventions.

17. Query Analytics

Fingerprinting, slow query log, intent classification (OLTP/analytics/vector), N+1 detection.

18. Schema-Aware Routing

Data temperature classification (hot/warm/cold), workload-type detection, automatic schema discovery.

19. Authentication Proxy

JWT, OAuth 2.0, LDAP, API key validation, and external identity claim-to-role mapping.

20. Rate Limiter

Token bucket, sliding window, and concurrency limiting. Per-tenant, per-user, per-IP, per-query cost.

21. Circuit Breaker

Adaptive failure detection with closed/open/half-open states and automatic recovery probes.

22. Multi-Tenancy

Tenant identification, pool isolation, schema routing, and per-tenant resource quotas.

CRDs for HeliosProxy, PoolProfile, RoutingRule, AuditPolicy, TenantQuota. Reconciler renders ConfigMap + Deployment + Service per CR; polls /topology to populate status. Owned objects auto-clean on kubectl delete.

Companion

45. Terraform Provider

Five resources mirror the operator CRDs: heliosproxy_instance, _pool_profile, _routing_rule, _audit_policy, _tenant_quota. Schema generated from the operator's Go types via local replace.

Companion

46. Pulumi Provider

Wraps the Terraform provider via pulumi-terraform-bridge. Same five resources surfaced as first-class Pulumi types in TypeScript / Python / Go / .NET.

Repositories (post-rename)

Repository	Purpose	Access
`HeliosDatabase/HeliosDB-Proxy`	Core proxy	Public →
`HeliosDatabase/HeliosDB-Proxy-Operator`	Kubernetes operator	Private
`HeliosDatabase/HeliosDB-Proxy-Plugins`	First-party WASM plugins + CLI	Public →
`HeliosDatabase/terraform-provider-HeliosDB-Proxy`	Terraform provider	Private
`HeliosDatabase/pulumi-HeliosDB-Proxy`	Pulumi provider	Private
`ghcr.io/heliosdatabase/hdb-heliosdb-proxy:1.7.0`	Container image (lowercase — GHCR convention)	Public →

Performance

Measured Performance

HeliosProxy adds minimal latency while dramatically improving throughput, caching, and availability.

42K

Queries/sec (pooled)

vs. 8.2K direct connection. 5x throughput improvement from connection pooling alone.

0.05ms

Cached Query Latency

L1 hot cache serves frequently accessed results in sub-microsecond time.

0.3ms

Connection Time

vs. 12ms direct connection establishment. 40x faster via connection pooling.

1.2s

Auto-Failover

Automatic failover with Transaction Replay. Where recovery is possible, clients experience a brief pause rather than an error; where it is not, a specific SQLSTATE.

Backend-Agnostic

Works With Any PostgreSQL Backend

HeliosProxy operates at the wire protocol level. All features work transparently with any PostgreSQL-wire-compatible database.

Backend	Compatibility	Notes
PostgreSQL 12+	Full	Including Amazon RDS, Aurora, Cloud SQL, Azure Database
HeliosDB Lite/Full	Full	Native topology integration for instant failover
CockroachDB	Full	PostgreSQL wire protocol compatible
YugabyteDB	Full	PostgreSQL wire protocol compatible
TimescaleDB	Full	Runs as PostgreSQL extension
Citus	Full	Runs as PostgreSQL extension
AlloyDB	Full	Google Cloud PostgreSQL-compatible

How We Compare

HeliosProxy vs The Competition

HeliosProxy isn’t just a connection pooler — it’s an AI-native database platform layer. Here’s how it compares to every alternative in the market.

Capability	PgBouncer	pgpool-II	PgCat	Odyssey	HAProxy	AWS RDS Proxy	HeliosProxy
Connection Pooling	3 modes	Yes	Yes	Yes	L4 only	Yes	3 modes + AI-aware
Multi-threaded	✗	✓	✓ (Rust)	✓ (C99)	✓ (C)	N/A	✓ (Rust)
Query Caching	✗	Basic	✗	✗	✗	✗	3-tier distributed
Load Balancing	✗	✓	✓	✗	✓	✓	✓ + schema-aware
Auto Failover	✗	✓	✓	✗	Basic (health-check)	✓	✓ + circuit breaker
Rate Limiting	✗	✗	✗	✗	Basic (stick-tables)	✗	Per-tenant, per-query
Multi-Tenancy	✗	✗	✗	✗	✗	✗	Full isolation (4 modes)
Auth Proxy	Basic	Basic	Basic	Basic	✗	IAM only	JWT/OAuth/LDAP/SAML
Query Analytics	✗	✗	✗	✗	L4/L7 stats only	CloudWatch	P50/P90/P99 + cost attr.
GraphQL Gateway	✗	✗	✗	✗	✗	✗	Auto-generated
WASM Plugins	✗	✗	✗	✗	✗	✗	✓ (sandboxed)
Branch-Aware	✗	✗	✗	✗	✗	✗	Git-like branching
AI/RAG Caching	✗	✗	✗	✗	✗	✗	Semantic + conversation
Query Rewriting	✗	✗	✗	✗	✗	✗	Tenant injection + optimization
Transaction Replay	✗	✗	✗	✗	✗	✗	In-session, no driver needed
Replay Verification	✗	✗	✗	✗	✗	✗	Response digest; 40001 on divergence
Session State Restore	✗	✗	✗	✗	✗	✗	SET, transactional + savepoint-scoped
Write Routing	✗	✗	✗	✗	Basic (port-based)	✗	TWR (any-node connect)
Sharding	✗	✗	✓	✗	✗	✗	Schema-aware routing
Vendor Lock-in	None	None	None	None	None	AWS only	None

10–100× Read Performance

3-tier distributed cache (L1 local <100μs, L2 Redis <5ms, L3 DB) with 85% hit rate in production. No competitor offers multi-tier caching.

100:1 Connection Multiplexing

10,000 concurrent tenant connections served by 100 database connections. 73% infrastructure cost reduction vs. PgBouncer’s 10:1 ratio.

Zero Vendor Lock-in

Deploy anywhere — Docker, Kubernetes, bare metal. Unlike AWS RDS Proxy, HeliosProxy works with any PostgreSQL-compatible database.

AI-Native Workload Optimization

Semantic query cache, RAG chunk caching, conversation context, and tool result cache. Purpose-built for AI/Agent database workloads.

14 Features No Competitor Has

WASM plugins, GraphQL gateway, branch-aware caching, AI workload optimization, in-session transaction replay, replay verification, session state restore, write routing, semantic caching, per-tenant analytics, query routing hints, batch coalescing, switchover buffer, transaction journal.

Single Component

Replaces PgBouncer + Redis + rate limiter + auth proxy + GraphQL server + analytics. One binary, one config file, one deployment.

HeliosProxy

Drop HeliosProxy into Claude Code & Codex CLI in 30 seconds

From Connection Router to Programmable Data-Plane

Real WASM Plugin Runtime

Ed25519 + OCI Artefacts

Replay Engine over the Journal

Zero-Downtime PG Major Versions

No More Simulated Failover

Built-in Admin Console

License Update

WASM Plugins, Real This Time

Transaction Replay — In-Session Failover

Time-Travel Replay

Zero-Downtime PostgreSQL Major-Version Upgrades

Built-in Admin Console

Hot-Path Performance & Correctness

Per-Node Checkout, No Global Lock

Lock-Free Atomic Counters

Zero-Allocation Parameter Parse

Concurrent Hits, Read-Lock Only

Benchmark: Previous → Latest release

Why HeliosProxy?

Connection Pooling

Multi-Tier Caching

GraphQL Gateway

WASM Plugins

Intelligent Query Routing

Query Rewriting & Optimization

Authentication Proxy

Multi-Tenancy

Query Analytics

Rate Limiting

The Write Journal & Operator Replay

What It Refuses To Do

Session State Across a Failover

Transparent Write Routing (TWR)

46 Feature ModulesIn One Component

1. Connection Pooling

2. Load Balancer

3. Health Checker

4. Request Pipeline

5. Batch Operations

6. Failover Controller

7. Transaction Replay

8. Session State Restore

9. Replay Verification

10. Switchover Buffer

11. Primary Tracker

12. Transaction Journal

13. Query Cache

14. Query Routing Hints

15. Lag-Aware Routing

16. Query Rewriter

17. Query Analytics

18. Schema-Aware Routing

19. Authentication Proxy

20. Rate Limiter

21. Circuit Breaker

22. Multi-Tenancy

23. WASM Plugin System

24. GraphQL Gateway

25. Anomaly Detection

26. Edge Mode

27. Plugin Host KV

28. Plugin Host Crypto

29. Plugin Signatures (Ed25519)

30. OCI Plugin Artefacts

31. Plugin Route-Block

32. Plugin Trust Root Config

33. Admin Web UI

34. Admin REST v2

35. Plugin: cost-governor

36. Plugin: ai-classifier

37. Plugin: token-budget

38. Plugin: llm-guardrail

39. Plugin: pgvector-router

40. Plugin: column-mask

41. Plugin: audit-chain

42. Plugin: residency-router

43. helios-plugin CLI

46 Feature Modules
In One Component

43. `helios-plugin` CLI