---
title: "HeliosProxy Feature Flags"
---

# HeliosProxy Feature Flags

HeliosProxy uses Cargo feature flags to control which modules are compiled into the binary. This allows operators to build a proxy tailored to their exact requirements, from a lightweight connection pooler to a full-featured intelligent proxy.

The authoritative list is the `[features]` table in `Cargo.toml`. This document tracks it flag-for-flag.

---

## Feature Flag Reference

### Default Features

| Feature | Default | Description |
|---------|---------|-------------|
| `pool-modes` | **Yes** | Session, Transaction, and Statement connection pooling. |

`pool-modes` is the only default feature (`default = ["pool-modes"]`). To build without it, pass `--no-default-features`.

### Core Proxy Features

All of the following are **off by default**. Enable them individually or via the `all-features` bundle.

| Feature | Pulls extra deps | Description |
|---------|------------------|-------------|
| `pool-modes` | None | Connection pooling modes (Session/Transaction/Statement). Enabled by default. |
| `ha-tr` | None | **Deprecated no-op.** Transaction Replay (in-session recovery, journal, `/api/replay`, `/api/shadow`) is part of the default build and is toggled by `tr_enabled` in `proxy.toml`. The feature name is kept so downstream mappings keep resolving. |
| `query-cache` | None | L1 hot / L2 warm query result caching (a semantic tier is planned). |
| `routing-hints` | None | SQL comment-based query routing hints. |
| `lag-routing` | None | Replica lag-aware routing with read-your-writes consistency. |
| `rate-limiting` | None | Token bucket, sliding window, and concurrency rate limiting. |
| `circuit-breaker` | None | Adaptive circuit breaker pattern per backend node. |
| `query-analytics` | None | Query fingerprinting, slow query log, N+1 detection, intent classification. |
| `multi-tenancy` | None | Tenant-aware routing, per-tenant pools, resource quotas. |
| `auth-proxy` | None | Proxy-level authentication scaffolding (JWT, OAuth, API keys). |
| `ldap-auth` | `ldap3` | LDAP search + bind auth. Implies `auth-proxy`. Off by default even within `auth-proxy` because it pulls the `ldap3` client and its rustls stack. |
| `query-rewriting` | None | Rule-based SQL query transformation. |
| `wasm-plugins` | `wasmtime` | Sandboxed WASM plugin runtime with hot-reload. |
| `graphql-gateway` | None | GraphQL-to-SQL gateway with schema introspection. |
| `schema-routing` | None | Schema-aware routing and workload classification. |
| `distribcache` | None | DistribCache library module (see caveat under Feature Details). |
| `anomaly-detection` | None | In-process anomaly heuristics: rate spikes, credential stuffing, SQL-injection patterns, novel query shapes. |
| `edge-proxy` | `lru` | Edge / geo proxy mode: cache-first handling, last-write-wins TTL coherence, pull-on-miss + invalidation push. |

### Topology Providers

| Feature | Default | Description |
|---------|---------|-------------|
| `postgres-topology` | No | PostgreSQL primary discovery via `pg_is_in_recovery()` polling. Used throughout `src/primary_tracker.rs`. |
| `heliosdb-topology` | No | Reserved for builds that embed HeliosProxy in a HeliosDB server. A standalone HeliosProxy does not use it; choose `postgres-topology`. |

Topology providers are independent of each other. Choose one based on your backend. If neither is enabled, the proxy operates in standalone mode with manual primary management via the Admin API.

### Observability

| Feature | Default | Description |
|---------|---------|-------------|
| `observability` | No | Reserved **no-op**. Historically pulled `prometheus`/`opentelemetry` without wiring any code; those unused dependencies were removed (they carried the protobuf advisory). `/metrics` and `/metrics/prometheus` are always served by the admin API. |

> **Note:** `observability = []` compiles nothing extra and activates no exporter,
> tracer, or metrics wiring; grep still finds zero `#[cfg(feature = "observability")]`
> guards in `src/`. Prometheus-style metrics are served regardless of this flag by the
> Admin HTTP API at `GET /metrics` and `GET /metrics/prometheus` (`src/admin.rs`).

### Bundle Features

| Feature | Description |
|---------|-------------|
| `all-features` | Every proxy feature module. Does **not** include a topology provider or `observability` -- add those separately. |
| `msrv-features` | MSRV CI verification bundle. Same as `all-features` **minus `wasm-plugins` and `ldap-auth`** (both pull heavy optional deps -- `wasmtime` and `ldap3` -- that slow the MSRV compile). |

`all-features` expands to: `pool-modes`, `ha-tr`, `query-cache`, `routing-hints`, `lag-routing`, `rate-limiting`, `circuit-breaker`, `query-analytics`, `multi-tenancy`, `auth-proxy`, `ldap-auth`, `query-rewriting`, `wasm-plugins`, `graphql-gateway`, `schema-routing`, `distribcache`, `anomaly-detection`, `edge-proxy`.

`msrv-features` expands to the same set **without** `wasm-plugins` and `ldap-auth`.

---

## Feature Details

### `pool-modes` -- Connection Pooling Modes

**Modules:** `src/pool/`

Enables three connection pooling modes that control when backend connections are returned to the pool.

| Mode | Return Trigger | Use Case |
|------|---------------|----------|
| Session | Client disconnect | Legacy applications, prepared statements, long sessions |
| Transaction | COMMIT / ROLLBACK | Web applications, microservices, APIs |
| Statement | Each individual statement | Read-heavy workloads, connection-constrained environments |

Includes prepared statement tracking, connection reset sequences, lease management, and pool hardening.

### `ha-tr` -- deprecated no-op (Transaction Replay is in the default build)

**Modules (always compiled):** `src/transaction_journal.rs`,
`src/failover_replay.rs`, `src/replay/`, `src/session_migrate.rs`, `src/cursor_restore.rs`,
`src/upgrade_orchestrator.rs`, `src/shadow_execute/`.

Transaction Replay is **on by default**; the `ha-tr` cargo feature gates nothing. The
runtime switch is `tr_enabled` in `proxy.toml` (`--tr=false` on the CLI). Setting it to
`false` stops write journaling, forces the effective `tr_mode` to `none`, and makes
`POST /api/replay` return `503`. `POST /api/shadow` stays available: it is an explicit
validation tool, not part of failover recovery.

In-session recovery is the same path the client always took: the proxy records the
statements, session state and response digests of an open transaction, and on a backend
fault re-homes the session to a new primary, restores its `SET` state and replays the
transaction under one `write_timeout_secs` deadline, verifying each replayed response
against what the client already saw. See [transaction-replay.md](/docs/proxy/transaction-replay/).

The operator tooling built on the same journal:

1. A recovery journal of committed transactions (statements, bound parameters, outcomes
   and `commit_seq`), held in memory by default and made durable with `[journal] dir`.
2. The operator-driven `POST /api/replay` endpoint, in `time_window` or
   `committed_history` mode — replay journaled transactions against a target backend, for
   failover validation, staging hydration or forensics.
3. `POST /api/shadow` — dual-execute a query against two backends and diff the results.
4. The `FailoverController`/`PrimaryTracker`/`SwitchoverBuffer` library components for
   embedded use.

`session_migrate` and `cursor_restore` are library modules and are **not** on the recovery
path. SQL-level `PREPARE`, temporary tables, cursors and advisory locks do not survive a
failover; protocol-level named prepared statements are re-prepared on the new primary.

Recovery is transparent where it can be. Where it cannot be — an unknown `COMMIT` outcome,
a response already partly delivered, a snapshot-pinned transaction — the client gets a
clear SQLSTATE (`08007`, `40001`, `08006`) instead of a silently wrong result.

### `query-cache` -- Query Caching

**Modules:** `src/cache/`

Two-tier query result cache, both tiers in process:

- **L1 (Hot):** In-process hash map with LRU eviction. Microsecond access.
- **L2 (Warm):** Larger shared cache with normalized query fingerprinting. Sub-millisecond access.
- **Semantic tier (planned):** similarity matching for near-duplicate queries is on the roadmap; `proxy.toml` has no setting for it and the current release builds L1 and L2 only.

Supports TTL-based expiration, table-based invalidation on writes, and cache bypass via SQL hints.

### `routing-hints` -- Query Routing Hints

**Modules:** `src/routing/`

Enables SQL comment-based routing directives (`/*helios:key=value,...*/`, parsed by `src/routing/hint_parser.rs`):

```sql
SELECT /*helios:route=primary*/ balance FROM accounts WHERE id = 1;
SELECT /*helios:route=standby*/ * FROM analytics_data;
```

The hint parser extracts directives from SQL comments and overrides the default routing decision made by the load balancer. Requires `[routing_hints] enabled = true` in `proxy.toml`.

### `lag-routing` -- Lag-Aware Routing

**Modules:** `src/lag/`

Monitors replication lag on all standby and replica nodes. Reads are routed only to nodes within the configured lag threshold.

Includes a read-your-writes (RYW) consistency module that tracks the last write LSN per session and ensures subsequent reads from that session go to a node that has replicated past that LSN.

### `rate-limiting` -- Rate Limiting

**Modules:** `src/rate_limit/`

Provides three rate limiting algorithms:

- **Token bucket:** Sustained rate with configurable burst.
- **Sliding window:** Fixed-window counting with sub-window smoothing.
- **Concurrency guard:** Limits the number of concurrent in-flight queries.

Supports per-user, per-tenant, and per-IP policies. Includes a query cost estimator that weights complex queries higher than simple ones.

### `circuit-breaker` -- Circuit Breaker

**Modules:** `src/circuit_breaker/`

Adaptive circuit breaker with three states:

| State | Behavior |
|-------|----------|
| Closed | Normal operation. Failures are counted. |
| Open | All requests to the affected node are rejected immediately. Entered after `failure_threshold` consecutive failures. |
| Half-Open | After `recovery_timeout_secs`, a single probe request is sent. If it succeeds, the circuit closes. If it fails, the circuit remains open. |

Each backend node has an independent breaker. The breaker uses a sliding-window failure counter to avoid false triggers from transient errors.

### `query-analytics` -- Query Analytics

**Modules:** `src/analytics/`

Real-time query analysis:

- **Fingerprinting:** Normalizes queries by replacing literals with placeholders, grouping identical query patterns.
- **Statistics:** Per-fingerprint execution count, latency histogram (P50/P95/P99), rows returned.
- **Slow query log:** Logs queries exceeding the configured threshold with full SQL, parameters, and execution time.
- **N+1 detection:** Identifies repeated identical queries within a session that indicate an N+1 query pattern.
- **Intent classification:** Classifies queries as OLTP, OLAP, DDL, or administrative.

### `multi-tenancy` -- Multi-Tenancy

**Modules:** `src/multi_tenancy/`

Tenant-aware proxy operation:

- **Identification:** Extracts tenant ID from connection metadata (database name, username, or application_name).
- **Isolation:** Per-tenant connection pools with independent sizing.
- **Quotas:** Per-tenant rate limits and maximum connection limits.
- **Schema isolation:** Optional schema-prefix transformation for shared-database multi-tenancy.

### `auth-proxy` -- Authentication Proxy

**Modules:** `src/auth/`

Proxy-level authentication scaffolding: JWT validation, OAuth 2.0 token flows, and API-key validation, plus a role mapper that translates authentication identities to PostgreSQL roles.

> Note: the wired `proxy.toml` `[auth]` section currently exposes only `mode = "passthrough" | "scram"` plus `auth_file` (see `ProxyConfig` in `src/config.rs`). LDAP is a separate feature -- see `ldap-auth` below.

### `ldap-auth` -- LDAP Authentication

**Implies:** `auth-proxy` · **Pulls:** `ldap3`

Search + bind authentication against an LDAP directory. Kept as a distinct feature (rather than folded into `auth-proxy`) because it pulls the `ldap3` client and its rustls TLS stack. Off by default even when `auth-proxy` is enabled; excluded from `msrv-features`.

### `query-rewriting` -- Query Rewriting

**Modules:** `src/rewriter/`

Rule-based SQL transformation engine. Rules are evaluated in order and can:

- Add schema prefixes to unqualified table names.
- Replace deprecated syntax with modern equivalents.
- Inject query hints for routing or caching.
- Redirect queries to different tables or schemas.

### `wasm-plugins` -- WASM Plugin System

**Modules:** `src/plugins/` · **Pulls:** `wasmtime`

Sandboxed WebAssembly plugin runtime:

- **Hooks:** query-start, query-complete, connection, and error events.
- **Hot-reload:** Plugins can be updated without restarting the proxy.
- **Sandbox:** Each plugin runs in an isolated WASM sandbox with configurable memory limits and an execution timeout.
- **Host functions:** Plugins can call back into the proxy to read metrics, log messages, and modify query routing.

Excluded from `msrv-features` because `wasmtime` significantly slows the MSRV compile.

### `graphql-gateway` -- GraphQL Gateway

**Modules:** `src/graphql/` (`src/graphql_gateway.rs`)

GraphQL endpoint (separate HTTP listener):

- **Schema introspection:** Reflects the database schema into a GraphQL schema.
- **Query translation:** Converts GraphQL queries into SQL.
- **Validation:** Validates GraphQL queries against the reflected schema before execution.

Tables are exposed via `[[graphql_gateway.tables]]` in `proxy.toml`.

### `schema-routing` -- Schema-Aware Routing

**Modules:** `src/schema_routing/`

Routes queries based on table-level metadata:

- **Data temperature:** Classify tables as hot, warm, or cold and route accordingly.
- **Workload type:** OLTP tables to low-latency nodes, analytics tables to read replicas.
- **Admin API:** Runtime management of schema routing rules.

### `distribcache` -- Distributed Cache (library module)

**Modules:** `src/distribcache/`

> **Library module:** `distribcache` is a **library-only module**. It is compiled behind `#[cfg(feature = "distribcache")]` in `src/lib.rs` but is **not** referenced anywhere outside its own module (grep for `distribcache::` outside `src/distribcache/` returns nothing), and there is **no `[distribcache]` section in `ProxyConfig`** -- `proxy.toml` cannot configure or activate it. Enabling the feature makes the module available to code linking the crate as a library; it does **not** turn on a turnkey distributed proxy cache on the data path. For an operator-facing result cache, use `query-cache` (and `edge-proxy` for cross-region invalidation).

The module itself implements multi-tier caching (L1 and L2 in process; an external Redis-compatible L3 tier is planned, and the current release contains no Redis client), workload classification, an access heatmap, and AI-specific strategies (embedding prefetch, conversation-context caching).

### `anomaly-detection` -- Anomaly Detection

**Modules:** `src/anomaly/` (runs on hardcoded `AnomalyConfig::default()` -- there is no `proxy.toml` anomaly section)

In-process, sliding-window heuristics with no external data store:

- **Rate spikes:** z-score-based traffic-spike detection.
- **Credential stuffing:** auth-burst / failed-login clustering.
- **SQL injection:** pattern heuristics over incoming SQL.
- **Novel query shapes:** flags query fingerprints not seen before.

Results are surfaced at the Admin API `/anomalies` endpoint.

### `edge-proxy` -- Edge / Geo Proxy

**Pulls:** `lru`

Cache-first edge/geo mode: home-authoritative clock, last-write-wins TTL coherence, pull-on-miss with server-pushed (SSE) invalidation over a PG-wire data plane. Edges register with, subscribe to, and receive invalidation from the home proxy via the Admin API `/api/edge` routes (`/register`, `/subscribe`, `/invalidate`) and the `[edge]` `proxy.toml` section.

---

## Recommended Combinations

### Lightweight Connection Pooler

Minimal overhead. Suitable for replacing PgBouncer.

```bash
cargo build --release --features "pool-modes"
```

Included: connection pooling (Session/Transaction/Statement), load balancing, health checking, basic failover.

### High-Availability Proxy

Connection pooling with full failover protection and topology discovery.

```bash
cargo build --release --features "pool-modes,postgres-topology"
```

Included: all of the above plus automatic primary discovery via PostgreSQL polling. Transaction Replay (in-session recovery, the recovery journal and the operator replay endpoints) is in every build; adding `ha-tr` changes nothing.

### Intelligent Query Proxy

Adds query-level intelligence to the HA proxy.

```bash
cargo build --release --features "pool-modes,postgres-topology,query-cache,routing-hints,lag-routing,query-analytics"
```

Included: all of the above plus query caching, routing hints, lag-aware routing, and query analytics.

### Enterprise Proxy

Full security and multi-tenancy stack.

```bash
cargo build --release --features "pool-modes,postgres-topology,query-cache,routing-hints,lag-routing,query-analytics,rate-limiting,circuit-breaker,multi-tenancy,auth-proxy,ldap-auth,query-rewriting,anomaly-detection"
```

### Full-Featured Proxy

Every proxy module enabled. Add a topology provider explicitly (the bundle omits it).

```bash
cargo build --release --features "all-features,postgres-topology"
```

> `observability` may be appended, but it is a no-op: it compiles nothing extra and
> wires no code (see the Observability note). The `/metrics` endpoints work without it.

### MSRV Verification

Matches the CI MSRV gate (Rust 1.86). Same as `all-features` minus `wasm-plugins` and `ldap-auth`.

```bash
cargo check --locked --features msrv-features
```

---

## See Also

- [Architecture](/docs/proxy/architecture/) -- Module map and data-flow pipeline
- [Configuration Reference](/docs/proxy/configuration/) -- Every configuration key documented
- [Deployment Guides](/docs/proxy/deployment/docker/) -- Standalone, Docker, and Kubernetes deployment