Configuration Reference (v3.1.0)

Configuration Reference (v3.1.0)

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

Table of Contents

1. Overview
2. Configuration File Format
3. Session Configuration
4. Lock Manager Configuration
5. Dump Configuration
6. Resource Quotas Configuration
7. Server Configuration
8. Authentication Configuration
9. Logging Configuration
10. Complete Configuration Example
11. Default Values Table
12. Tuning Recommendations
13. Security Considerations
14. Performance Tuning Tips

Overview

HeliosDB Nano 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):

1. Command-line: --config /path/to/config.toml
2. Environment: $HELIOSDB_CONFIG
3. Current directory: ./config.toml
4. User home: ~/.config/heliosdb/config.toml
5. 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-nano config validate --config config.toml

# Show effective configuration (with overrides)
heliosdb-nano 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-nano
heliosdb-nano hash-password

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

# Or via command line
echo -n "mypassword" | heliosdb-nano 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 Nano 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

---

See Also

• CLI Reference - Command-line interface
• In-Memory Mode Guide - In-memory operations
• Dump/Restore Guide - Backup procedures
• Security Hardening Guide - Security best practices

---

Version: 3.1.0 Last Updated: 2025-12-08 Maintained by: HeliosDB Team