Configuration

Configure LivenDB for your deployment environment.

LivenDB reads liven.toml (and optionally liven.conf) from the current working directory, or the file passed with --config / LIVEN_CONFIG. Relative paths inside that file (storage.data_directory and the ZTNA certificate paths) resolve against the config file's directory, not the process CWD. Environment variables prefixed with LIVEN_ or LIVENDB_ override file values, and the embedded API accepts a programmatic LivenConfig. The precedence is built-in defaults → config file → environment variables.

Configuration Structure

• Server — network, ports, and connection settings
• Storage — data directory, segment size, and fsync policy
• Limits — streams, file descriptors, index budget, and scan limits
• Security — auth mode, master key, and mTLS/ZTNA certificates

Server Configuration

Storage Configuration

Limits Configuration

limits.max_segment_size_mb is parsed but never read. Use storage.max_segment_size_mb instead.

Retention Configuration

Retention is segment-level: an inactive segment is deleted only when every live record in it is older than its stream's max-age. The active segment is left for rollover/compaction.

Security Configuration

security.auth_key.system_stream and security.auth_key.allow_local_auto_generation are currently parsed but not applied; the auth stream is hardcoded to auth_keys. mTLS covers the native TCP listener only — REST and WebSocket traffic remains HTTP.

Example Configuration File

[server]
environment = "production"
host = "0.0.0.0"
db_port = 43121
webui_port = 43120
[storage]
data_directory = "/var/lib/liven"
max_segment_size_mb = 256
sync_mode = "always"
[limits]
max_concurrent_streams = 64
max_open_file_descriptors = 128
max_index_ram_mb = 1024
max_scan_results = 500000
[security]
mode = "auth_key"
# master_key = "..."       # prefer LIVEN_SECURITY_MASTER_KEY
[security.ztna]
enabled = false
# cert_path = "./certs/server.crt"
# key_path = "./certs/server.key"
# client_ca_path = "./certs/ca.crt"

Configuration Profiles

Development

[server]
environment = "development"
host = "127.0.0.1"
[security]
mode = "none"
[limits]
max_concurrent_streams = 16
max_open_file_descriptors = 32

Production

[server]
environment = "production"
host = "0.0.0.0"
[security]
mode = "auth_key"
[security.ztna]
enabled = true
cert_path = "/etc/liven/certs/server.crt"
key_path = "/etc/liven/certs/server.key"
client_ca_path = "/etc/liven/certs/ca.crt"
[limits]
max_concurrent_streams = 64
max_open_file_descriptors = 128
max_index_ram_mb = 1024
max_scan_results = 500000

Edge / Embedded

[limits]
max_concurrent_streams = 8
max_open_file_descriptors = 16
max_index_ram_mb = 32
max_scan_results = 10000

Index RAM Auto-Detection

When max_index_ram_mb is not explicitly set, Liven allocates 25% of detected host RAM, clamped to 32 MiB–4096 MiB. If detection fails, it falls back to 512 MiB. The 4 GiB value is an auto-detection ceiling, not a hard cap: an explicit larger value is accepted.

The limit is enforced against compound_key.len() + 128 bytes per live key: a 64-byte primary-index node and a 64-byte timestamp-index node. Allocator overhead and compaction scratch memory are still additional. Measured process RSS is roughly 157–192 bytes per key for the key lengths below.

On Linux, detection reads /proc/meminfo (host-visible memory), not cgroup limits. In containers, set max_index_ram_mb explicitly.

At the accounting limit, new keys are rejected with IndexRamLimitExceeded. There is no eviction or spill. A database whose rebuilt index exceeds a too-small limit still opens by default: Liven loads it, logs the overage, and rejects only new keys (overwrites, deletes, and reads continue). --strict-recoveryrefuses to open instead.

Monitoring

status() returns connection/subscriber counters plus index usage: max_connections, broadcast_capacity, active_connections, broadcast_subscribers, index_ram_bytes, index_ram_limit_bytes, index_high_water_bytes, and index_high_water_reached. Use process RSS for total process memory.

Best Practices

• Set the index budget explicitly in containers — auto detection sees host RAM.
• Keep keys short — key length and stream name are part of every index entry.
• Use [storage] max_segment_size_mb — the duplicate under [limits] is ignored.
• Use environment variables for secrets — set LIVEN_SECURITY_MASTER_KEY instead of committing it.
• Restart after config changes — configuration is read at startup.