Configuration File Reference (v3.5)

Overview

HeliosDB-Lite uses TOML configuration files for server-wide settings. This document provides comprehensive reference for all configuration options in config.toml.

Version: 3.5.8

Quick Start

# Copy example configuration
cp config.example.toml config.toml

# Edit configuration
nano config.toml

# Start server with configuration
heliosdb-lite start --config config.toml

# Start REPL with configuration
heliosdb-lite repl --config config.toml

Configuration Sections

• Storage
• Encryption
• Server
• Performance
• Audit
• Optimizer
• Authentication
• Compression
• Materialized Views
• Vector Indexes
• Session
• Locks
• Dump
• Resource Quotas

Storage Section

Controls database storage, WAL, and persistence.

[storage]
path = "./heliosdb-data"
memory_only = false
wal_enabled = true
wal_sync_mode = "sync"
cache_size = 536870912
compression = "Zstd"
time_travel_enabled = true
query_timeout_ms = 0
statement_timeout_ms = 0
transaction_isolation = "READ_COMMITTED"

Options

Option	Type	Default	Description
path	String	"./heliosdb-data"	Database directory path
memory_only	Boolean	false	Use in-memory database
wal_enabled	Boolean	true	Enable write-ahead log
wal_sync_mode	String	"sync"	WAL sync mode: sync, async, group_commit
cache_size	Integer	536870912	Cache size in bytes (512MB)
compression	String	"Zstd"	Default compression: None, Zstd, Lz4
time_travel_enabled	Boolean	true	Enable automatic versioning
query_timeout_ms	Integer	0	Query timeout (0 = unlimited)
statement_timeout_ms	Integer	0	Statement timeout (0 = unlimited)
transaction_isolation	String	"READ_COMMITTED"	Isolation level

Examples

# Development: In-memory database
[storage]
memory_only = true
wal_enabled = false

# Production: Durable, fast
[storage]
path = "/var/lib/heliosdb"
wal_sync_mode = "group_commit"
query_timeout_ms = 30000
cache_size = 2147483648  # 2GB

# Write-heavy: Async WAL
[storage]
wal_sync_mode = "async"
time_travel_enabled = false

Encryption Section

Transparent data encryption (TDE) configuration.

[encryption]
enabled = false
algorithm = "Aes256Gcm"
rotation_interval_days = 90

[encryption.key_source]
Environment = "HELIOSDB_ENCRYPTION_KEY"

Options

Option	Type	Default	Description
enabled	Boolean	false	Enable encryption at rest
algorithm	String	"Aes256Gcm"	Encryption algorithm
rotation_interval_days	Integer	90	Key rotation interval
key_source	Object	Environment variable	Key source configuration

Key Source Options

# Option 1: Environment variable
[encryption.key_source]
Environment = "HELIOSDB_ENCRYPTION_KEY"

# Option 2: File
[encryption.key_source]
File = "/secure/path/to/key"

# Option 3: Cloud KMS
[encryption.key_source.Kms]
provider = "aws"
key_id = "arn:aws:kms:us-east-1:123:key/abc"

Server Section

Network server configuration.

[server]
listen_addr = "127.0.0.1"
port = 5432
oracle_port = 1521
max_connections = 100
tls_enabled = false
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"

Options

Option	Type	Default	Description
listen_addr	String	"127.0.0.1"	Listen address (0.0.0.0 for all)
port	Integer	5432	PostgreSQL protocol port
oracle_port	Integer	1521	Oracle TNS port (null to disable)
max_connections	Integer	100	Maximum connections
tls_enabled	Boolean	false	Enable TLS/SSL
tls_cert_path	String	None	TLS certificate path
tls_key_path	String	None	TLS private key path

Examples

# Local development
[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 10

# Production
[server]
listen_addr = "0.0.0.0"
port = 5432
max_connections = 1000
tls_enabled = true
tls_cert_path = "/etc/heliosdb/ssl/cert.pem"
tls_key_path = "/etc/heliosdb/ssl/key.pem"

Performance Section

Performance tuning parameters.

[performance]
worker_threads = 0
query_timeout_secs = 300
simd_enabled = true
parallel_query = true

Options

Option	Type	Default	Description
worker_threads	Integer	CPU count	Worker threads (0 = auto)
query_timeout_secs	Integer	300	Legacy timeout setting
simd_enabled	Boolean	true	Enable SIMD optimizations
parallel_query	Boolean	true	Enable parallel execution

Optimizer Section

Query optimizer configuration.

[optimizer]
enabled = true
enable_seqscan = true
enable_indexscan = true
enable_hashjoin = true
enable_mergejoin = true
enable_nestloop = true
seq_page_cost = 1.0
random_page_cost = 4.0
cpu_tuple_cost = 0.01
cpu_index_tuple_cost = 0.005

Options

Option	Type	Default	Description
enabled	Boolean	true	Enable optimizer
enable_seqscan	Boolean	true	Allow sequential scans
enable_indexscan	Boolean	true	Allow index scans
enable_hashjoin	Boolean	true	Allow hash joins
enable_mergejoin	Boolean	true	Allow merge joins
enable_nestloop	Boolean	true	Allow nested loop joins
seq_page_cost	Float	1.0	Sequential page cost
random_page_cost	Float	4.0	Random page cost
cpu_tuple_cost	Float	0.01	CPU tuple cost
cpu_index_tuple_cost	Float	0.005	CPU index tuple cost

Examples

# SSD optimized
[optimizer]
random_page_cost = 1.1  # Low for SSDs

# Force index usage
[optimizer]
enable_seqscan = false

# Disable specific joins
[optimizer]
enable_hashjoin = false
enable_mergejoin = false

Authentication Section

User authentication configuration.

[authentication]
enabled = false
method = "trust"
jwt_secret = "secret-key"
jwt_expiration_secs = 86400
password_hash_algorithm = "argon2"
users_file = "/etc/heliosdb/users.json"

Options

Option	Type	Default	Description
enabled	Boolean	false	Enable authentication
method	String	"trust"	Auth method: trust, password, jwt, ldap
jwt_secret	String	None	JWT secret key
jwt_expiration_secs	Integer	86400	JWT expiration (24h)
password_hash_algorithm	String	"argon2"	Hash: argon2, bcrypt, pbkdf2
users_file	String	None	Users database file

Examples

# Development: No auth
[authentication]
method = "trust"

# Production: JWT auth
[authentication]
enabled = true
method = "jwt"
jwt_secret = "CHANGE-THIS-IN-PRODUCTION"
jwt_expiration_secs = 3600  # 1 hour

# Password auth
[authentication]
enabled = true
method = "password"
password_hash_algorithm = "argon2"
users_file = "/etc/heliosdb/users.json"

Compression Section

Data compression configuration.

[compression]
default_type = "Zstd"
level = 3
enable_alp = true
enable_fsst = true
min_size_bytes = 1024

Options

Option	Type	Default	Description
default_type	String	"Zstd"	Default compression type
level	Integer	3	Compression level (1-22)
enable_alp	Boolean	true	Enable ALP for numerics
enable_fsst	Boolean	true	Enable FSST for strings
min_size_bytes	Integer	1024	Minimum size to compress

Examples

# Maximum compression
[compression]
default_type = "Zstd"
level = 19

# Fast compression
[compression]
default_type = "Lz4"
level = 1

# No compression
[compression]
default_type = "None"

Materialized Views Section

Materialized view refresh configuration.

[materialized_views]
auto_refresh_default = false
default_max_cpu_percent = 15
refresh_check_interval_secs = 60
max_concurrent_refreshes = 2

Options

Option	Type	Default	Description
auto_refresh_default	Boolean	false	Default auto-refresh
default_max_cpu_percent	Integer	15	Max CPU for refresh
refresh_check_interval_secs	Integer	60	Check interval
max_concurrent_refreshes	Integer	2	Concurrent refreshes

Vector Section

Vector index configuration.

[vector]
default_index_type = "hnsw"
hnsw_ef_construction = 200
hnsw_m = 16
enable_pq = true
pq_subvectors = 8
pq_bits = 8

Options

Option	Type	Default	Description
default_index_type	String	"hnsw"	Index type: flat, hnsw, ivf
hnsw_ef_construction	Integer	200	HNSW construction param
hnsw_m	Integer	16	HNSW connections
enable_pq	Boolean	true	Enable product quantization
pq_subvectors	Integer	8	PQ subvector count
pq_bits	Integer	8	PQ bits per subvector

Examples

# High quality index
[vector]
hnsw_ef_construction = 400
hnsw_m = 32

# Fast, low memory
[vector]
hnsw_ef_construction = 100
hnsw_m = 8
enable_pq = true

Session Section

Session management configuration.

[session]
timeout_secs = 3600
max_sessions_per_user = 10
cleanup_interval_secs = 300

Options

Option	Type	Default	Description
timeout_secs	Integer	3600	Session timeout in seconds (1 hour)
max_sessions_per_user	Integer	10	Maximum concurrent sessions per user
cleanup_interval_secs	Integer	300	Cleanup check interval (5 minutes)

Examples

# Short-lived sessions (API use)
[session]
timeout_secs = 900
max_sessions_per_user = 100

# Long-lived sessions (interactive)
[session]
timeout_secs = 86400
max_sessions_per_user = 5

Locks Section

Lock management and deadlock detection configuration.

[locks]
timeout_ms = 30000
deadlock_check_interval_ms = 100
max_lock_holders = 10000

Options

Option	Type	Default	Description
timeout_ms	Integer	30000	Lock acquisition timeout (30 seconds)
deadlock_check_interval_ms	Integer	100	Deadlock detection interval
max_lock_holders	Integer	10000	Maximum concurrent lock holders

Examples

# High-concurrency workload
[locks]
timeout_ms = 60000
deadlock_check_interval_ms = 50
max_lock_holders = 50000

# Low-latency requirements
[locks]
timeout_ms = 5000
deadlock_check_interval_ms = 10

Dump Section

Database backup and dump scheduling configuration.

[dump]
auto_dump_enabled = false
schedule = ""
compression = "zstd"
max_dump_size_mb = 10000
keep_dumps = 10
dump_dir = ".dumps"

Options

Option	Type	Default	Description
auto_dump_enabled	Boolean	false	Enable scheduled dumps
schedule	String	""	Cron-style schedule (e.g., "0 */6 * * *")
compression	String	"zstd"	Compression: zstd, gzip, none
max_dump_size_mb	Integer	10000	Max dump file size before rolling
keep_dumps	Integer	10	Number of old dumps to keep (0 = all)
dump_dir	String	".dumps"	Directory to store dump files

Examples

# Hourly automated dumps
[dump]
auto_dump_enabled = true
schedule = "0 * * * *"
compression = "zstd"
keep_dumps = 24

# Daily dumps with maximum compression
[dump]
auto_dump_enabled = true
schedule = "0 2 * * *"
compression = "zstd"
max_dump_size_mb = 50000
keep_dumps = 30
dump_dir = "/var/backups/heliosdb"

# No auto-dump, manual only
[dump]
auto_dump_enabled = false
compression = "gzip"

Cron Schedule Format

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, Sunday = 0)
│ │ │ │ │
* * * * *

Examples:
  "0 */6 * * *"  - Every 6 hours
  "0 2 * * *"    - Daily at 2:00 AM
  "0 0 * * 0"    - Weekly on Sunday at midnight
  "*/15 * * * *" - Every 15 minutes

Resource Quotas Section

Per-user resource limits and quotas.

[resource_quotas]
memory_limit_per_user_mb = 1024
max_concurrent_queries = 100
query_timeout_secs = 300

Options

Option	Type	Default	Description
memory_limit_per_user_mb	Integer	1024	Memory limit per user (1 GB)
max_concurrent_queries	Integer	100	Maximum concurrent queries per user
query_timeout_secs	Integer	300	Query execution timeout (5 minutes)

Examples

# Multi-tenant with strict limits
[resource_quotas]
memory_limit_per_user_mb = 256
max_concurrent_queries = 10
query_timeout_secs = 60

# Analytics workload (generous limits)
[resource_quotas]
memory_limit_per_user_mb = 8192
max_concurrent_queries = 20
query_timeout_secs = 3600

Complete Configuration Examples

Development

[storage]
memory_only = true
wal_enabled = false

[server]
listen_addr = "127.0.0.1"
port = 5432

[authentication]
method = "trust"

[performance]
worker_threads = 2

Production

[storage]
path = "/var/lib/heliosdb"
wal_sync_mode = "group_commit"
query_timeout_ms = 30000
cache_size = 2147483648

[encryption]
enabled = true
[encryption.key_source]
Environment = "HELIOSDB_KEY"

[server]
listen_addr = "0.0.0.0"
max_connections = 1000
tls_enabled = true
tls_cert_path = "/etc/heliosdb/ssl/cert.pem"
tls_key_path = "/etc/heliosdb/ssl/key.pem"

[authentication]
enabled = true
method = "jwt"
jwt_secret = "CHANGE-THIS"

[audit]
enabled = true
log_path = "/var/log/heliosdb/audit.log"

High-Performance SSD

[storage]
cache_size = 4294967296  # 4GB

[optimizer]
random_page_cost = 1.1

[performance]
worker_threads = 0
simd_enabled = true

[compression]
default_type = "Lz4"
level = 1

See Also

• REPL Command Reference - Interactive commands
• SQL Settings Reference - Runtime settings
• Deployment Guide - Production deployment