Configuration Reference¶

HyperbyteDB loads configuration in this order (later sources override earlier):

1. Built-in defaults
2. TOML config file (path from --config / -c flag; defaults to ./config.toml)
3. Environment variables with prefix HYPERBYTEDB__

Environment Variable Format¶

HYPERBYTEDB__<SECTION>__<KEY>=value

Double underscores (__) separate the section name and key. For nested sections, add another level:

HYPERBYTEDB__SERVER__PORT=9090
HYPERBYTEDB__STORAGE__WAL_DIR=/var/lib/hyperbytedb/wal
HYPERBYTEDB__CLUSTER__PEERS="node2:8086,node3:8086"

[server]¶

HTTP server settings.

[storage]¶

Local directories for the write-ahead log and metadata store. Time-series data lives in embedded chDB MergeTree tables under [chdb].session_data_path.

[flush]¶

Controls the background WAL-to-chDB flush pipeline.

[chdb]¶

Embedded ClickHouse (chDB) query engine settings.

[auth]¶

Authentication configuration.

When enabled, /write and /query require valid credentials. Health/metrics and other public routes, plus admin-only internal/cluster APIs, are documented in Authentication.

[cardinality]¶

Limits to prevent unbounded series growth from high-cardinality data.

If a write exceeds these limits, it returns HTTP 422 with a cardinality limit exceeded error.

[cluster]¶

Master-master peer-to-peer clustering with Raft consensus for schema mutations.

[cluster.replication]¶

Per-node coordinator replication behavior. If the whole block is omitted, mode is async (fire-and-forget fan-out, same as legacy).

[logging]¶

[statement_summary]¶

Query statement tracking for debugging and observability.

When enabled, recently executed statements are accessible via GET /api/v1/statements. Password literals in stored query samples are redacted.

[disk]¶

Periodic free-space checks on WAL, metadata, and chDB data directories. When free space drops below readonly_threshold_mb, the node enters read-only mode: /write returns HTTP 507 and /health reports unavailable until space recovers.

Prometheus metrics: hyperbytedb_disk_free_bytes{path}, hyperbytedb_disk_readonly_events_total.

[hinted_handoff]¶

Hinted handoff stores writes destined for unreachable peers and replays them when the peer recovers.

[rate_limit]¶

HTTP rate limiting for /write and /query. See Rate limiting for behavior, tuning, and client guidance.

Rejected requests increment hyperbytedb_rate_limit_denied_total (documented in Administration).

[retention]¶

Controls the background retention enforcement loop. Per-policy duration values are stored in metadata (CREATE/ALTER RETENTION POLICY).

Example: Minimal Single-Node¶

[server]
bind_address = "0.0.0.0"
port = 8086

[storage]
wal_dir = "./wal"
meta_dir = "./meta"

[flush]
interval_secs = 10

[chdb]
session_data_path = "./chdb_data"
pool_size = 4

[logging]
level = "info"

Example: Production Cluster Node¶

[server]
bind_address = "0.0.0.0"
port = 8086
query_timeout_secs = 60
max_concurrent_queries = 32
tls_enabled = true
tls_cert_path = "/etc/hyperbytedb/cert.pem"
tls_key_path = "/etc/hyperbytedb/key.pem"

[storage]
wal_dir = "/var/lib/hyperbytedb/wal"
meta_dir = "/var/lib/hyperbytedb/meta"

[flush]
interval_secs = 10

[chdb]
session_data_path = "/var/lib/hyperbytedb/chdb"

[cluster]
enabled = true
node_id = 1
cluster_addr = "10.0.0.1:8086"
replication_log_dir = "/var/lib/hyperbytedb/replication_log"
raft_dir = "/var/lib/hyperbytedb/raft"

[auth]
enabled = true

[cardinality]
max_tag_values_per_measurement = 100000
max_measurements_per_database = 10000

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

Example: Environment Variable Overrides¶

export HYPERBYTEDB__SERVER__PORT=9090
export HYPERBYTEDB__SERVER__QUERY_TIMEOUT_SECS=60
export HYPERBYTEDB__STORAGE__WAL_DIR=/var/lib/hyperbytedb/wal
export HYPERBYTEDB__STORAGE__META_DIR=/var/lib/hyperbytedb/meta
export HYPERBYTEDB__CHDB__SESSION_DATA_PATH=/var/lib/hyperbytedb/chdb
export HYPERBYTEDB__SERVER__MAX_CONCURRENT_QUERIES=32
export HYPERBYTEDB__LOGGING__LEVEL=debug
export HYPERBYTEDB__LOGGING__FORMAT=json
export HYPERBYTEDB__RETENTION__INTERVAL=5m

See Also¶

• Installation — Deployment methods
• Administration — Operational tuning
• Authentication — Enabling auth, credentials, admin for internal routes
• Advanced features — Clustering, TLS, S3