HeliosProxy Configuration Reference

HeliosProxy Configuration Reference

Complete reference for all HeliosProxy configuration options.

---

Configuration File Format

HeliosProxy uses TOML format for configuration files.

heliosdb-proxy --config /path/to/config.toml

---

Top-Level Options

Option	Type	Default	Description
listen_address	string	"0.0.0.0:5432"	Address for client connections
admin_address	string	"0.0.0.0:9090"	Address for admin API
tr_enabled	bool	true	Enable transaction replay
tr_mode	string	"session"	Transaction replay mode
write_timeout_secs	u64	30	Write timeout during failover

Transaction Replay Modes (tr_mode)

Mode	Description
none	No transaction replay
session	Re-establish session only
select	Re-execute SELECT queries
transaction	Full transaction replay

---

Pool Mode Configuration ([pool_mode])

Controls connection pooling behavior.

[pool_mode]
mode = "transaction"
max_pool_size = 100
min_idle = 10
idle_timeout_secs = 600
max_lifetime_secs = 3600
acquire_timeout_secs = 5
reset_query = "DISCARD ALL"
prepared_statement_mode = "track"

Option	Type	Default	Description
mode	string	"session"	Pooling mode: session, transaction, statement
max_pool_size	u32	100	Maximum connections per node
min_idle	u32	10	Minimum idle connections
idle_timeout_secs	u64	600	Idle connection timeout
max_lifetime_secs	u64	3600	Maximum connection lifetime
acquire_timeout_secs	u64	5	Connection acquire timeout
reset_query	string	"DISCARD ALL"	Query to reset connection state
prepared_statement_mode	string	"disable"	Prepared statement handling

Pooling Modes

Mode	Connection Returns	Best For
session	On client disconnect	Legacy apps, prepared statements
transaction	After COMMIT/ROLLBACK	Web apps, microservices
statement	After each statement	Simple queries, high concurrency

Prepared Statement Modes

Mode	Behavior
disable	No prepared statement support (safest)
track	Track and recreate on new connections
named	Use protocol-level named statements

---

Connection Pool Configuration ([pool])

Basic connection pool settings.

[pool]
min_connections = 2
max_connections = 100
idle_timeout_secs = 300
max_lifetime_secs = 1800
acquire_timeout_secs = 30
test_on_acquire = true

Option	Type	Default	Description
min_connections	usize	2	Minimum connections per node
max_connections	usize	100	Maximum connections per node
idle_timeout_secs	u64	300	Idle connection timeout
max_lifetime_secs	u64	1800	Maximum connection lifetime
acquire_timeout_secs	u64	30	Connection acquire timeout
test_on_acquire	bool	true	Test connection before use

---

Load Balancer Configuration ([load_balancer])

Controls query routing to backend nodes.

[load_balancer]
read_strategy = "round_robin"
read_write_split = true
latency_threshold_ms = 100

Option	Type	Default	Description
read_strategy	string	"round_robin"	Read query routing strategy
read_write_split	bool	true	Enable read/write splitting
latency_threshold_ms	u64	100	Latency threshold for unhealthy

Routing Strategies (read_strategy)

Strategy	Description
round_robin	Rotate through nodes equally
weighted_round_robin	Rotate based on node weights
least_connections	Route to least loaded node
latency_based	Route to lowest latency node
random	Random node selection

---

Health Check Configuration ([health])

Backend health monitoring.

[health]
check_interval_secs = 5
check_timeout_secs = 3
failure_threshold = 3
success_threshold = 2
check_query = "SELECT 1"

Option	Type	Default	Description
check_interval_secs	u64	5	Health check interval
check_timeout_secs	u64	3	Health check timeout
failure_threshold	u32	3	Failures before unhealthy
success_threshold	u32	2	Successes before healthy
check_query	string	"SELECT 1"	Health check query

---

Node Configuration ([[nodes]])

Backend node definitions. Use [[nodes]] for each node.

[[nodes]]
host = "primary.example.com"
port = 5432
http_port = 8080
role = "primary"
weight = 100
enabled = true
name = "primary-1"

[[nodes]]
host = "standby-1.example.com"
port = 5432
role = "standby"
weight = 50

[[nodes]]
host = "replica-1.example.com"
port = 5432
role = "replica"
weight = 25

Option	Type	Default	Description
host	string	required	Node hostname or IP
port	u16	required	PostgreSQL port
http_port	u16	8080	HTTP admin port
role	string	required	Node role
weight	u32	100	Load balancing weight
enabled	bool	true	Node is active
name	string	optional	Human-readable name

Node Roles

Role	Description
primary	Read/write node (required)
standby	Synchronous standby
replica	Read-only replica

---

TLS Configuration ([tls])

Optional TLS settings for client connections.

[tls]
enabled = true
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"
ca_path = "/path/to/ca.pem"
require_client_cert = false

Option	Type	Default	Description
enabled	bool	false	Enable TLS
cert_path	string	required	Server certificate path
key_path	string	required	Server key path
ca_path	string	optional	CA certificate for client auth
require_client_cert	bool	false	Require client certificates

---

Complete Example

# HeliosProxy Configuration
# Full example with all options

listen_address = "0.0.0.0:5433"
admin_address = "0.0.0.0:9090"
tr_enabled = true
tr_mode = "session"
write_timeout_secs = 30

# Connection pooling mode
[pool_mode]
mode = "transaction"
max_pool_size = 100
min_idle = 10
idle_timeout_secs = 600
max_lifetime_secs = 3600
acquire_timeout_secs = 5
reset_query = "DISCARD ALL"
prepared_statement_mode = "track"

# Basic pool settings
[pool]
min_connections = 5
max_connections = 100
idle_timeout_secs = 300
max_lifetime_secs = 1800
acquire_timeout_secs = 30
test_on_acquire = true

# Load balancing
[load_balancer]
read_strategy = "least_connections"
read_write_split = true
latency_threshold_ms = 50

# Health checks
[health]
check_interval_secs = 5
check_timeout_secs = 3
failure_threshold = 3
success_threshold = 2
check_query = "SELECT 1"

# Primary node
[[nodes]]
host = "db-primary.internal"
port = 5432
http_port = 8080
role = "primary"
weight = 100
enabled = true
name = "primary"

# Standby node (sync replication)
[[nodes]]
host = "db-standby-1.internal"
port = 5432
http_port = 8080
role = "standby"
weight = 100
enabled = true
name = "standby-1"

# Read replica
[[nodes]]
host = "db-replica-1.internal"
port = 5432
http_port = 8080
role = "replica"
weight = 50
enabled = true
name = "replica-1"

# TLS (optional)
[tls]
enabled = false
# cert_path = "/etc/heliosproxy/server.crt"
# key_path = "/etc/heliosproxy/server.key"

---

Environment Variable Overrides

Configuration values can be overridden with environment variables:

HELIOS_PROXY_LISTEN_ADDRESS=0.0.0.0:5433
HELIOS_PROXY_ADMIN_ADDRESS=0.0.0.0:9090
HELIOS_PROXY_POOL_MODE=transaction
HELIOS_PROXY_MAX_POOL_SIZE=200

---

Configuration Validation

The proxy validates configuration on startup:

1. At least one node must be configured
2. A primary node must exist
3. max_connections must be >= min_connections
4. All required fields must be present

Invalid configurations will prevent startup with a descriptive error message.

---

Admin API Endpoints

The admin API provides runtime information and management.

Endpoint	Method	Description
/health	GET	Proxy health status
/pool/stats	GET	Connection pool statistics
/nodes	GET	Backend node status
/nodes/{name}/enable	POST	Enable a node
/nodes/{name}/disable	POST	Disable a node
/config	GET	Current configuration
/metrics	GET	Prometheus metrics

Pool Stats Response

{
  "mode": "transaction",
  "total_connections": 50,
  "active_leases": 12,
  "idle_connections": 38,
  "waiting_requests": 0,
  "connections_created": 1234,
  "connections_closed": 1184
}

Node Status Response

{
  "nodes": [
    {
      "name": "primary",
      "host": "db-primary.internal",
      "port": 5432,
      "role": "primary",
      "healthy": true,
      "active_connections": 15,
      "latency_ms": 0.5
    }
  ]
}

---

See Also

• Release Notes
• Feature Roadmap
• Tutorials