Configuration Reference (v3.1.0)¶

Version: 3.1.0 Status: Production-Ready Last Updated: 2025-12-08

Table of Contents¶

Overview
Configuration File Format
Session Configuration
Lock Manager Configuration
Dump Configuration
Resource Quotas Configuration
Server Configuration
Authentication Configuration
Logging Configuration
Complete Configuration Example
Default Values Table
Tuning Recommendations
Security Considerations
Performance Tuning Tips

Overview¶

HeliosDB-Lite v3.1.0 uses TOML format for configuration. Configuration files provide centralized control over:

Session management and timeouts
Lock manager behavior
Dump/restore automation
Resource quotas and limits
Authentication and authorization
Logging and monitoring

Configuration File Locations (checked in order):

Command-line: --config /path/to/config.toml
Environment: $HELIOSDB_CONFIG
Current directory: ./config.toml
User home: ~/.config/heliosdb/config.toml
System-wide: /etc/heliosdb/config.toml

Loading Priority: - Command-line flags override config file - Environment variables override config file - Config file overrides built-in defaults

Configuration File Format¶

Basic Structure:

# config.toml

[server]
# Server settings

[session]
# Session management

[locks]
# Lock manager

[dump]
# Dump/restore automation

[resource_quotas]
# Resource limits

[auth]
# Authentication

[logging]
# Logging configuration

Validation:

# Validate configuration file
heliosdb-lite config validate --config config.toml

# Show effective configuration (with overrides)
heliosdb-lite config show --config config.toml

Session Configuration¶

Controls multi-user session management and transaction isolation.

Configuration Section¶

[session]
# Session timeout in seconds (idle sessions terminated)
timeout_secs = 3600  # 1 hour

# Maximum sessions per user
max_sessions_per_user = 10

# Default isolation level for new sessions
# Options: "READ_COMMITTED", "REPEATABLE_READ", "SERIALIZABLE"
default_isolation_level = "READ_COMMITTED"

# Enable session statistics tracking
enable_stats = true

# Session cleanup interval (seconds)
cleanup_interval_secs = 300  # 5 minutes

Options Reference¶

Option	Type	Default	Description
`timeout_secs`	Integer	`3600`	Idle session timeout in seconds
`max_sessions_per_user`	Integer	`10`	Maximum concurrent sessions per user
`default_isolation_level`	String	`"READ_COMMITTED"`	Default transaction isolation level
`enable_stats`	Boolean	`true`	Track session statistics
`cleanup_interval_secs`	Integer	`300`	How often to check for expired sessions

Isolation Level Values¶

Value	ANSI Level	Guarantees	Use Case
`READ_COMMITTED`	Read Committed	No dirty reads	Web apps, interactive queries
`REPEATABLE_READ`	Repeatable Read	Consistent snapshot	Reports, exports
`SERIALIZABLE`	Serializable	Full serializability	Financial transactions

Examples¶

Development (permissive):

[session]
timeout_secs = 28800  # 8 hours
max_sessions_per_user = 50
default_isolation_level = "READ_COMMITTED"

Production (strict):

[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 5
default_isolation_level = "REPEATABLE_READ"
cleanup_interval_secs = 60

High-concurrency (optimized):

[session]
timeout_secs = 3600
max_sessions_per_user = 100
default_isolation_level = "READ_COMMITTED"  # Lowest overhead
enable_stats = false  # Reduce contention

Lock Manager Configuration¶

Controls concurrency control, deadlock detection, and lock timeouts.

Configuration Section¶

[locks]
# Lock acquisition timeout in milliseconds
timeout_ms = 30000  # 30 seconds

# Deadlock detection interval in milliseconds
detection_interval_ms = 1000  # 1 second

# Enable lock statistics
enable_stats = true

# Lock table initial capacity (performance tuning)
initial_capacity = 10000

Options Reference¶

Option	Type	Default	Description
`timeout_ms`	Integer	`30000`	Maximum time to wait for lock
`detection_interval_ms`	Integer	`1000`	How often to check for deadlocks
`enable_stats`	Boolean	`true`	Track lock acquisition stats
`initial_capacity`	Integer	`10000`	Initial hash table size for locks

Examples¶

Low-latency (aggressive timeouts):

[locks]
timeout_ms = 5000  # 5 seconds
detection_interval_ms = 500  # 500ms

Long-running transactions:

[locks]
timeout_ms = 300000  # 5 minutes
detection_interval_ms = 5000  # 5 seconds

High-concurrency workload:

[locks]
timeout_ms = 10000
detection_interval_ms = 1000
initial_capacity = 100000  # Large lock table
enable_stats = false  # Reduce overhead

Dump Configuration¶

Controls automated backup, dump scheduling, and retention policies.

Configuration Section¶

[dump]
# Auto-dump schedule (cron syntax, empty = disabled)
schedule = ""  # Example: "0 */6 * * *" (every 6 hours)

# Auto-dump when WAL size exceeds threshold (bytes, 0 = disabled)
wal_size_threshold = 1073741824  # 1GB

# Default compression type
# Options: "none", "lz4", "zstd"
compression = "zstd"

# Compression level (1-22 for zstd, 1-12 for lz4)
compression_level = 3

# Default dump directory
dump_dir = "/var/backups/heliosdb"

# Keep dump history for N days
history_retention_days = 30

# Warn on dirty shutdown
warn_on_dirty_shutdown = true

# Batch size for dump operations (rows)
batch_size = 10000

Options Reference¶

Option	Type	Default	Description
`schedule`	String	`""`	Cron expression for auto-dumps
`wal_size_threshold`	Integer	`1073741824`	WAL size triggering auto-dump (bytes)
`compression`	String	`"zstd"`	Compression algorithm
`compression_level`	Integer	`3`	Compression level
`dump_dir`	String	`"/var/backups/heliosdb"`	Default dump directory
`history_retention_days`	Integer	`30`	Dump history retention
`warn_on_dirty_shutdown`	Boolean	`true`	Warn about unsaved changes
`batch_size`	Integer	`10000`	Rows per dump batch

Cron Schedule Examples¶

Expression	Meaning
`"0 /6 * *"`	Every 6 hours
`"0 2 * * *"`	Daily at 2 AM
`"0 2 * * 0"`	Weekly on Sunday at 2 AM
`"0 0 1 * *"`	Monthly on 1st at midnight
`"/15 * * *"`	Every 15 minutes

Examples¶

Daily backups (production):

[dump]
schedule = "0 2 * * *"  # 2 AM daily
compression = "zstd"
compression_level = 9  # Maximum compression for archival
dump_dir = "/var/backups/heliosdb/daily"
history_retention_days = 90
warn_on_dirty_shutdown = true

Hourly backups (high-frequency):

[dump]
schedule = "0 * * * *"  # Every hour
wal_size_threshold = 536870912  # 512MB (trigger on size too)
compression = "lz4"  # Faster compression
compression_level = 1
dump_dir = "/var/backups/heliosdb/hourly"
history_retention_days = 7

WAL-triggered only:

[dump]
schedule = ""  # No scheduled dumps
wal_size_threshold = 1073741824  # Dump when WAL > 1GB
compression = "zstd"
compression_level = 3

Disabled (manual dumps only):

[dump]
schedule = ""
wal_size_threshold = 0  # Disabled
warn_on_dirty_shutdown = true  # Still warn

Resource Quotas Configuration¶

Controls per-user resource limits and system-wide constraints.

Configuration Section¶

[resource_quotas]
# Per-user memory limit (bytes, 0 = unlimited)
memory_limit_per_user = 1073741824  # 1GB

# Per-user connection limit
connection_limit_per_user = 10

# Per-transaction timeout (seconds, 0 = unlimited)
transaction_timeout_secs = 300  # 5 minutes

# Query execution timeout (seconds, 0 = unlimited)
query_timeout_secs = 60  # 1 minute

# System-wide memory limit (bytes, 0 = unlimited)
system_memory_limit = 8589934592  # 8GB

# Maximum total connections (all users)
max_total_connections = 100

Options Reference¶

Option	Type	Default	Description
`memory_limit_per_user`	Integer	`1073741824`	Per-user memory limit (bytes)
`connection_limit_per_user`	Integer	`10`	Max connections per user
`transaction_timeout_secs`	Integer	`300`	Transaction timeout
`query_timeout_secs`	Integer	`60`	Query execution timeout
`system_memory_limit`	Integer	`8589934592`	System-wide memory limit
`max_total_connections`	Integer	`100`	Total connection limit

Examples¶

Development (unlimited):

[resource_quotas]
memory_limit_per_user = 0  # Unlimited
connection_limit_per_user = 0
transaction_timeout_secs = 0
query_timeout_secs = 0

Production (strict limits):

[resource_quotas]
memory_limit_per_user = 536870912  # 512MB
connection_limit_per_user = 5
transaction_timeout_secs = 60  # 1 minute
query_timeout_secs = 30  # 30 seconds
system_memory_limit = 4294967296  # 4GB total
max_total_connections = 50

High-concurrency (balanced):

[resource_quotas]
memory_limit_per_user = 268435456  # 256MB
connection_limit_per_user = 20
transaction_timeout_secs = 120
query_timeout_secs = 60
max_total_connections = 500

Server Configuration¶

Controls network server settings and connection handling.

Configuration Section¶

[server]
# Listen port
port = 5432

# Bind address (127.0.0.1 = localhost, 0.0.0.0 = all interfaces)
listen = "127.0.0.1"

# Maximum concurrent connections
max_connections = 100

# Connection timeout (seconds)
connection_timeout_secs = 30

# TCP keepalive interval (seconds, 0 = disabled)
keepalive_interval_secs = 60

# Enable TCP_NODELAY (disable Nagle's algorithm)
tcp_nodelay = true

Options Reference¶

Option	Type	Default	Description
`port`	Integer	`5432`	TCP listen port
`listen`	String	`"127.0.0.1"`	Bind address
`max_connections`	Integer	`100`	Maximum concurrent connections
`connection_timeout_secs`	Integer	`30`	Connection timeout
`keepalive_interval_secs`	Integer	`60`	TCP keepalive interval
`tcp_nodelay`	Boolean	`true`	Disable Nagle's algorithm

Examples¶

Development (localhost only):

[server]
port = 5432
listen = "127.0.0.1"
max_connections = 10

Production (public access):

[server]
port = 5432
listen = "0.0.0.0"
max_connections = 200
connection_timeout_secs = 60
keepalive_interval_secs = 30
tcp_nodelay = true

Load-balanced (high availability):

[server]
port = 5432
listen = "0.0.0.0"
max_connections = 500
connection_timeout_secs = 10
keepalive_interval_secs = 15
tcp_nodelay = true

Authentication Configuration¶

Controls user authentication and authorization.

Configuration Section¶

[auth]
# Authentication method: "trust", "password", "scram-sha-256"
method = "password"

# Password hashing algorithm: "argon2", "bcrypt"
password_hash = "argon2"

# Argon2 parameters (if password_hash = "argon2")
argon2_memory_kb = 4096
argon2_iterations = 3
argon2_parallelism = 1

# User definitions (development only - use external auth in production)
[[auth.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=4096,t=3,p=1$..."
roles = ["admin", "read", "write"]

[[auth.users]]
username = "readonly"
password_hash = "$argon2id$v=19$m=4096,t=3,p=1$..."
roles = ["read"]

Options Reference¶

Option	Type	Default	Description
`method`	String	`"password"`	Authentication method
`password_hash`	String	`"argon2"`	Password hashing algorithm
`argon2_memory_kb`	Integer	`4096`	Argon2 memory cost
`argon2_iterations`	Integer	`3`	Argon2 time cost
`argon2_parallelism`	Integer	`1`	Argon2 parallelism

Authentication Methods¶

Method	Security	Use Case
`trust`	None	Development only
`password`	Medium	Internal networks
`scram-sha-256`	High	Production environments

Generating Password Hashes¶

# Using heliosdb-lite
heliosdb-lite hash-password

# Prompt:
# Enter password: ********
# Password hash: $argon2id$v=19$m=4096,t=3,p=1$...

# Or via command line
echo -n "mypassword" | heliosdb-lite hash-password --stdin

Examples¶

Development (trust):

[auth]
method = "trust"  # No authentication

Production (SCRAM-SHA-256):

[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 65536  # 64MB for high security
argon2_iterations = 5

Logging Configuration¶

Controls logging output, levels, and formats.

Configuration Section¶

[logging]
# Log level: "error", "warn", "info", "debug", "trace"
level = "info"

# Log format: "text", "json"
format = "text"

# Log output: "stdout", "stderr", "file"
output = "stdout"

# Log file path (if output = "file")
file_path = "/var/log/heliosdb/heliosdb.log"

# Enable log rotation
rotate = true

# Max log file size (bytes)
max_size = 104857600  # 100MB

# Number of old log files to keep
max_backups = 10

Options Reference¶

Option	Type	Default	Description
`level`	String	`"info"`	Logging level
`format`	String	`"text"`	Log format
`output`	String	`"stdout"`	Log destination
`file_path`	String	`"/var/log/heliosdb/heliosdb.log"`	Log file path
`rotate`	Boolean	`true`	Enable log rotation
`max_size`	Integer	`104857600`	Max log file size
`max_backups`	Integer	`10`	Old log files to keep

Examples¶

Development (verbose):

[logging]
level = "debug"
format = "text"
output = "stdout"

Production (structured):

[logging]
level = "info"
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 104857600  # 100MB
max_backups = 30

High-volume (minimal):

[logging]
level = "warn"  # Only warnings and errors
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 524288000  # 500MB
max_backups = 5

Complete Configuration Example¶

Production-ready configuration:

# config.toml - HeliosDB Lite v3.1.0

[server]
port = 5432
listen = "0.0.0.0"
max_connections = 200
connection_timeout_secs = 60
keepalive_interval_secs = 30
tcp_nodelay = true

[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 10
default_isolation_level = "READ_COMMITTED"
enable_stats = true
cleanup_interval_secs = 300

[locks]
timeout_ms = 30000  # 30 seconds
detection_interval_ms = 1000
enable_stats = true
initial_capacity = 10000

[dump]
schedule = "0 2 * * *"  # Daily at 2 AM
wal_size_threshold = 1073741824  # 1GB
compression = "zstd"
compression_level = 3
dump_dir = "/var/backups/heliosdb"
history_retention_days = 30
warn_on_dirty_shutdown = true
batch_size = 10000

[resource_quotas]
memory_limit_per_user = 1073741824  # 1GB
connection_limit_per_user = 10
transaction_timeout_secs = 300  # 5 minutes
query_timeout_secs = 60  # 1 minute
system_memory_limit = 8589934592  # 8GB
max_total_connections = 200

[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 8192
argon2_iterations = 3
argon2_parallelism = 1

[[auth.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=8192,t=3,p=1$..."
roles = ["admin"]

[logging]
level = "info"
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 104857600
max_backups = 30

Default Values Table¶

Section	Option	Default	Type
session	timeout_secs	3600	Integer
	max_sessions_per_user	10	Integer
	default_isolation_level	"READ_COMMITTED"	String
	enable_stats	true	Boolean
	cleanup_interval_secs	300	Integer
locks	timeout_ms	30000	Integer
	detection_interval_ms	1000	Integer
	enable_stats	true	Boolean
	initial_capacity	10000	Integer
dump	schedule	""	String
	wal_size_threshold	1073741824	Integer
	compression	"zstd"	String
	compression_level	3	Integer
	dump_dir	"/var/backups/heliosdb"	String
	history_retention_days	30	Integer
	warn_on_dirty_shutdown	true	Boolean
	batch_size	10000	Integer
resource_quotas	memory_limit_per_user	1073741824	Integer
	connection_limit_per_user	10	Integer
	transaction_timeout_secs	300	Integer
	query_timeout_secs	60	Integer
	system_memory_limit	8589934592	Integer
	max_total_connections	100	Integer
server	port	5432	Integer
	listen	"127.0.0.1"	String
	max_connections	100	Integer
	connection_timeout_secs	30	Integer
	keepalive_interval_secs	60	Integer
	tcp_nodelay	true	Boolean
auth	method	"password"	String
	password_hash	"argon2"	String
	argon2_memory_kb	4096	Integer
	argon2_iterations	3	Integer
	argon2_parallelism	1	Integer
logging	level	"info"	String
	format	"text"	String
	output	"stdout"	String
	rotate	true	Boolean
	max_size	104857600	Integer
	max_backups	10	Integer

Tuning Recommendations¶

Development Environment¶

[session]
timeout_secs = 28800  # 8 hours
max_sessions_per_user = 50

[locks]
timeout_ms = 60000  # 1 minute (long debugging sessions)

[resource_quotas]
memory_limit_per_user = 0  # Unlimited
transaction_timeout_secs = 0

[auth]
method = "trust"  # No auth

[logging]
level = "debug"
format = "text"

Production Environment¶

[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 5

[locks]
timeout_ms = 10000  # 10 seconds

[resource_quotas]
memory_limit_per_user = 536870912  # 512MB
transaction_timeout_secs = 120

[auth]
method = "scram-sha-256"

[logging]
level = "info"
format = "json"
output = "file"

High-Concurrency Environment¶

[session]
max_sessions_per_user = 100
default_isolation_level = "READ_COMMITTED"  # Lowest overhead

[locks]
timeout_ms = 5000  # Aggressive
initial_capacity = 100000  # Large lock table

[resource_quotas]
memory_limit_per_user = 268435456  # 256MB
max_total_connections = 500

[server]
max_connections = 500
tcp_nodelay = true

Security Considerations¶

1. Authentication¶

# ❌ NEVER use in production
[auth]
method = "trust"

# ✅ Always use strong authentication
[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 65536  # High cost
argon2_iterations = 5

2. Network Binding¶

# ❌ Avoid exposing to public internet
[server]
listen = "0.0.0.0"  # All interfaces

# ✅ Bind to localhost or specific IP
[server]
listen = "127.0.0.1"  # Localhost only
# OR
listen = "10.0.1.50"  # Specific internal IP

3. Resource Limits¶

# ✅ Always set resource limits in production
[resource_quotas]
memory_limit_per_user = 1073741824
connection_limit_per_user = 10
transaction_timeout_secs = 300
query_timeout_secs = 60

4. Logging¶

# ✅ Enable structured logging for security monitoring
[logging]
level = "info"
format = "json"  # Machine-readable for SIEM
output = "file"

Performance Tuning Tips¶

1. Lock Contention¶

# Reduce lock timeout for high-throughput
[locks]
timeout_ms = 5000  # Fail fast
detection_interval_ms = 500

2. Memory Usage¶

# For large datasets, increase memory limits
[resource_quotas]
memory_limit_per_user = 2147483648  # 2GB
system_memory_limit = 17179869184  # 16GB

3. Connection Pooling¶

# Increase connection limits for connection pools
[server]
max_connections = 500

[resource_quotas]
connection_limit_per_user = 50
max_total_connections = 500

4. Dump Performance¶

# Use LZ4 for faster dumps
[dump]
compression = "lz4"
compression_level = 1
batch_size = 50000  # Larger batches

5. Session Management¶

# Reduce overhead with longer cleanup intervals
[session]
cleanup_interval_secs = 600  # 10 minutes
enable_stats = false  # Disable if not monitoring

Configuration Reference (v3.1.0)¶

Table of Contents¶

Overview¶

Configuration File Format¶

Session Configuration¶

Configuration Section¶

Options Reference¶

Isolation Level Values¶

Examples¶

Lock Manager Configuration¶

Configuration Section¶

Options Reference¶

Examples¶

Dump Configuration¶

Configuration Section¶

Options Reference¶

Cron Schedule Examples¶

Examples¶

Resource Quotas Configuration¶

Configuration Section¶

Options Reference¶

Examples¶

Server Configuration¶

Configuration Section¶

Options Reference¶

Examples¶

Authentication Configuration¶

Configuration Section¶

Options Reference¶

Authentication Methods¶

Generating Password Hashes¶

Examples¶

Logging Configuration¶

Configuration Section¶

Options Reference¶

Examples¶

Complete Configuration Example¶

Default Values Table¶

Tuning Recommendations¶

Development Environment¶

Production Environment¶

High-Concurrency Environment¶

Security Considerations¶

1. Authentication¶

2. Network Binding¶

3. Resource Limits¶

4. Logging¶

Performance Tuning Tips¶

1. Lock Contention¶

2. Memory Usage¶

3. Connection Pooling¶

4. Dump Performance¶

5. Session Management¶

See Also¶