---
title: "HeliosProxy v1.0.0 Release Notes"
---

# HeliosProxy v1.0.0 Release Notes

## Overview

HeliosProxy v1.0.0 marks the transformation from a basic connection router into an **intelligent, AI-ready database proxy** for modern applications. This release includes 14 major features spanning connection pooling, resilience, enterprise capabilities, and distributed caching.

---

## Highlights

- **Connection Pooling Modes** - Session, Transaction, and Statement pooling for 100x connection efficiency
- **Intelligent Caching** - Query caching with TTL, invalidation, and distributed L1/L2/L3 cache tiers
- **AI/Agent Native** - First-class support for RAG pipelines, agentic workflows, and vector operations
- **Enterprise Ready** - Multi-tenancy, authentication proxy, rate limiting, and WASM plugin extensibility
- **High Availability** - Circuit breaker, replica lag-aware routing, and automatic failover

---

## New Features

### Foundation

#### 1. Connection Pooling Modes (Feature Flag: `pool-modes`)

Three pooling modes to reduce backend connection overhead:

| Mode | Behavior | Best For |
|------|----------|----------|
| **Session** | 1:1 client-to-backend mapping | Legacy apps, prepared statements |
| **Transaction** | Return after COMMIT/ROLLBACK | Web apps, microservices |
| **Statement** | Return after each statement | Read-heavy, connection-starved envs |

```toml
[pool_mode]
mode = "transaction"
max_pool_size = 100
min_idle = 10
idle_timeout_secs = 600
```

#### 2. Query Caching

Transparent query result caching with configurable TTL and invalidation strategies:

- LRU eviction with memory limits
- Table-based invalidation on writes
- Cache bypass via SQL hints

```toml
[cache]
enabled = true
max_memory_mb = 512
default_ttl_secs = 60
```

#### 3. Query Routing Hints

Control query routing via SQL comments:

```sql
SELECT /* helios:route=primary */ * FROM orders;
SELECT /* helios:route=standby */ * FROM analytics;
SELECT /* helios:cache=skip */ * FROM live_data;
```

#### 4. Replica Lag-Aware Routing

Automatically route queries to replicas within acceptable lag thresholds:

```toml
[routing]
max_replica_lag_ms = 100
lag_check_interval_secs = 1
```

### Resilience & Control

#### 5. Rate Limiting & Query Throttling

Protect backends from overload:

```toml
[rate_limit]
queries_per_second = 1000
burst_size = 100
per_user = true
```

#### 6. Circuit Breaker Pattern

Prevent cascade failures with automatic circuit breaking:

- **Closed**: Normal operation
- **Open**: Reject requests when errors exceed threshold
- **Half-Open**: Probe for recovery

```toml
[circuit_breaker]
failure_threshold = 5
recovery_timeout_secs = 30
```

#### 7. Query Analytics & Slow Query Log

Built-in query performance monitoring:

- Query frequency and latency histograms
- Slow query logging with configurable threshold
- No pg_stat_statements required

```toml
[analytics]
enabled = true
slow_query_threshold_ms = 100
```

### Enterprise Features

#### 8. Multi-Tenancy Support

Isolate tenants with dedicated pools and quotas:

```toml
[[tenants]]
id = "tenant_a"
max_connections = 50
rate_limit = 500
databases = ["tenant_a_db"]
```

#### 9. Authentication Proxy

Proxy-level authentication with multiple backends:

- LDAP integration
- JWT validation
- Certificate-based auth

#### 10. Query Rewriting

Transform queries transparently:

- Schema prefixing for multi-tenancy
- Query normalization
- Deprecated syntax migration

### Extensibility & Integration

#### 11. WASM Plugin System (Feature Flag: `wasm-plugins`)

Extend proxy behavior with WebAssembly plugins:

```toml
[[plugins]]
name = "audit_logger"
path = "/plugins/audit.wasm"
config = { log_level = "info" }
```

Plugin hooks:
- `on_query_start`
- `on_query_complete`
- `on_connection`
- `on_error`

#### 12. GraphQL-to-SQL Gateway (Feature Flag: `graphql`)

Automatic GraphQL endpoint generation:

```toml
[graphql]
enabled = true
endpoint = "/graphql"
introspection = true
```

#### 13. Schema-Aware Routing

Route queries based on table/schema metadata:

```toml
[[schema_routes]]
tables = ["events", "logs"]
target = "analytics_replica"

[[schema_routes]]
tables = ["orders", "payments"]
target = "primary"
```

### Distributed Intelligence

#### 14. Helios-DistribCache (Feature Flag: `distribcache`)

Multi-tier intelligent caching for AI workloads:

**Cache Tiers:**
- **L1**: In-process (microseconds)
- **L2**: Shared memory (sub-millisecond)
- **L3**: Distributed cluster (milliseconds)

**Workload Classification:**
- OLTP (transactional)
- OLAP (analytical)
- Vector (similarity search)
- AI/RAG (embedding pipelines)

**AI-Specific Optimizations:**
- Embedding prefetch for RAG pipelines
- Conversation context caching for agents
- Branch-aware caching for experiments

```toml
[distribcache]
enabled = true
l1_size_mb = 64
l2_size_mb = 512
l3_nodes = ["cache1:6379", "cache2:6379"]

[distribcache.ai]
embedding_prefetch = true
conversation_ttl_secs = 3600
```

---

## Configuration

### Minimal Configuration

```toml
listen_address = "127.0.0.1:5433"
admin_address = "127.0.0.1:9090"

[pool_mode]
mode = "transaction"
max_pool_size = 100

[[nodes]]
host = "127.0.0.1"
port = 5432
role = "primary"
```

---

## Build Options

```bash
# Minimal build
cargo build --release -p heliosdb-proxy

# With connection pooling modes
cargo build --release -p heliosdb-proxy --features pool-modes

# With distributed caching
cargo build --release -p heliosdb-proxy --features distribcache

# Full feature build
cargo build --release -p heliosdb-proxy --features pool-modes,distribcache,wasm-plugins,graphql
```

---

## Migration Guide

### From Direct HeliosDB Connections

1. Deploy HeliosProxy between application and HeliosDB
2. Update connection strings to point to proxy address
3. Start with `mode = "session"` for compatibility
4. Gradually migrate to `mode = "transaction"` for efficiency

### From PgBouncer

HeliosProxy supports similar pooling modes with enhanced features:

| PgBouncer | HeliosProxy | Notes |
|-----------|-------------|-------|
| `session` | `session` | Direct mapping |
| `transaction` | `transaction` | Direct mapping |
| `statement` | `statement` | Direct mapping |
| N/A | Query caching | New capability |
| N/A | AI workload routing | New capability |

---

## Breaking Changes

None - this is the initial release.

---

## Known Limitations

1. **Statement pooling** does not support server-side prepared statements
2. **GraphQL gateway** requires schema introspection enabled on backend
3. **WASM plugins** have 100ms execution timeout per hook
4. **DistribCache L3** requires external Redis-compatible cluster

---

## Performance Benchmarks

Measured on representative fixtures; reproduce on your own hardware.

| Scenario | Direct Connection | HeliosProxy (Transaction Mode) |
|----------|-------------------|--------------------------------|
| Connection overhead | 50-200ms | <1ms (pooled) |
| Simple SELECT | 0.5ms | 0.6ms |
| Cached SELECT | N/A | 0.05ms |
| Connections @ 1000 QPS | 1000 | 10-50 |

---

## Documentation

  - `pool-modes-tutorial.sh`
  - `ha-pool-failover-tutorial.sh`
  - `distribcache-tutorial.sh`

---

## Contributors

HeliosDB Team