HeliosProxy

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.
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
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

Transaction Replay (TR)

Oracle-grade TAF+TAC merged functionality for PostgreSQL. HeliosProxy journals all statements within a transaction and automatically replays them on a new node after failover, with full result verification to guarantee consistency.

Statement journaling — Logs every statement with bound parameters, result checksums, row counts, and execution timing
Savepoint support — Tracks savepoints and supports rollback-to-savepoint within the journal for accurate replay
Result verification — Verifies replayed results match originals via checksums and row counts, detecting any divergence
Configurable retry — Failed statements are retried up to a configurable maximum (default: 3 retries) with automatic backoff
WAL synchronization — Waits for the standby to catch up to the transaction's start LSN before replaying, ensuring data consistency
Replay statistics — Tracks active replays, completion counts, statement totals, and per-statement success/failure metrics

heliosproxy.toml + SQL

# Transaction Replay configuration
[transaction_replay]
enabled = true
verify_results = true
statement_timeout_ms = 30000
retry_on_error = true
max_retries = 3
wait_for_wal_sync = true
max_wal_lag_bytes = 0

[transaction_replay.journal]
max_entries = 10000
max_size = "64MB"

-- Transaction replayed after failover
BEGIN;
INSERT INTO orders (user_id, total)
  VALUES (42, 99.99);
SAVEPOINT sp1;
UPDATE inventory SET qty = qty - 1
  WHERE product_id = 7;
COMMIT;
-- checksum verified: OK
-- rows matched: OK

High Availability

Cursor Restore

Saves and restores cursor state after failover, allowing seamless resumption of result set iteration without losing position. Applications iterating through large result sets survive node failures transparently.

Position tracking — Tracks cursor name, original query, bound parameters, and current row position for every open cursor
Scrollable cursors — Supports forward-only, backward, and bidirectional scrollable cursors with direction preservation
WITH HOLD support — Preserves WITH HOLD cursor semantics across failover, maintaining cross-transaction cursor state
Automatic recreation — Re-executes the original query on the new node, then skips to the saved position using MOVE
Per-session limits — Configurable maximum cursors per session (default: 100) to prevent resource exhaustion
Session-level restore — Batch-restores all open cursors for a session during failover in a single operation

SQL

-- Declare a cursor over a large table
DECLARE user_cursor CURSOR FOR
  SELECT * FROM users
  ORDER BY created_at;

-- Fetch first 500 rows
FETCH 500 FROM user_cursor;
-- position: 500

-- Node fails! HeliosProxy restores:
-- 1. Re-declare cursor on new node
DECLARE user_cursor CURSOR FOR
  SELECT * FROM users
  ORDER BY created_at;

-- 2. Skip to saved position
MOVE 500 IN user_cursor;

-- 3. App continues seamlessly
FETCH 100 FROM user_cursor;
-- returns rows 501-600

High Availability

Session State Migration

Preserves and restores complete session state during failover, including SET parameters, prepared statements, and optionally temporary tables. Applications maintain their full session context when transparently moved to a new node.

SET parameter tracking — Captures timezone, search_path, client_encoding, datestyle, intervalstyle, application_name, and any custom variables
Prepared statement restore — Saves and re-creates all prepared statements with their parameter types on the new node
Temporary table migration — Optional migration of session-local temp tables including schema and data (disabled by default for performance)
SET statement generation — Automatically generates the minimal sequence of SET and PREPARE statements to restore the complete session
Custom variable support — Tracks arbitrary SET variables beyond PostgreSQL built-ins for application-specific session state
Scalable tracking — Supports up to 10,000 concurrent sessions with per-session state snapshots

heliosproxy.toml

# Session State Migration
[session_migration]
enabled = true
max_sessions = 10000
migrate_temp_tables = false

# Tracked session parameters
# (automatically captured on SET)
# - timezone
# - search_path
# - client_encoding
# - datestyle
# - intervalstyle
# - application_name
# - any custom SET variables

# Example: after failover, proxy runs:
# SET timezone TO 'America/New_York'
# SET search_path TO myapp, public
# SET client_encoding TO 'UTF8'
# SET datestyle TO 'ISO, MDY'
# SET app.tenant_id TO '42'
# PREPARE my_query (integer)
#   AS SELECT * FROM users
#   WHERE id = $1

Complete Platform

17 Enterprise Features
In One Component

HeliosProxy replaces an entire stack of infrastructure components with a single, purpose-built connection router.

1. Connection Pooling

Session, Transaction, Statement modes with up to 100:1 multiplexing.

2. Multi-Tier Caching

L1 local, L2 distributed, L3 semantic caching with auto-invalidation.

3. Rate Limiting

Per-tenant, per-user, per-query rate limiting with burst support.

4. Circuit Breaker

Automatic failure detection, traffic rerouting, and recovery.

5. Query Analytics

Slow query logging, pattern analysis, and real-time metrics.

6. Multi-Tenancy Routing

Automatic tenant isolation with schema, RLS, or database-level separation.

7. Authentication Proxy

JWT, OAuth 2.0, LDAP, and API key validation at the proxy layer.

8. GraphQL Gateway

Auto-generated GraphQL API from database schema with subscriptions.

9. WASM Plugins

Extend with custom WebAssembly plugins. Sandboxed, hot-reloadable.

10. Query Routing

Lag-aware, workload-classified, temperature-based query routing.

11. Query Rewriting

Automatic tenant injection, normalization, and optimization.

12. AI Workload Optimization

RAG chunk caching, conversation context, semantic query matching.

13. Schema-Aware Routing

Data temperature classification with hot, warm, and cold tiers.

14. Deployment Flexibility

Docker, Kubernetes, or bare metal. Horizontally scalable.

15. Transaction Replay

Oracle-grade TAF+TAC. Journals and replays transactions after failover with checksum verification.

16. Cursor Restore

Saves cursor state and position, recreates on new nodes after failover seamlessly.

17. Session Migration

Preserves SET parameters, prepared statements, and temp tables across failover.

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

Transaction Replay (TR)

Cursor Restore

Session State Migration

17 Enterprise FeaturesIn One Component

1. Connection Pooling

2. Multi-Tier Caching

3. Rate Limiting

4. Circuit Breaker

5. Query Analytics

6. Multi-Tenancy Routing

7. Authentication Proxy

8. GraphQL Gateway

9. WASM Plugins

10. Query Routing

11. Query Rewriting

12. AI Workload Optimization

13. Schema-Aware Routing

14. Deployment Flexibility

15. Transaction Replay

16. Cursor Restore

17. Session Migration

Available in Professional and Enterprise Tiers

17 Enterprise Features
In One Component