Configuration Reference

Tip

Looking for a ready-to-use config file? See the Reference Config File for a complete TOML with all defaults, or generate one with frogdb-server --generate-config.

This reference documents all configuration options available in FrogDB. Default values and types are extracted directly from the source code and are always up to date.

Legend: The Runtime column shows whether a field can be changed at runtime via CONFIG SET:

• ✓ — mutable at runtime
• ✗ — immutable (requires restart)
• — — not exposed via CONFIG GET/SET

Fields with a different CONFIG parameter name show it below the TOML key.

Configuration File Format

FrogDB uses TOML for configuration files. Pass the config file path with --config:

frogdb-server --config /etc/frogdb/frogdb.toml

frogdb.toml

[server]
bind = "127.0.0.1"
port = 6379

[persistence]
enabled = true
data-dir = "/var/lib/frogdb"

Configuration can also be set via environment variables with the FROGDB_ prefix (e.g., FROGDB_SERVER__PORT=6380).

---

Server

Network and connection settings.

[server]

Option	Type	Default	Runtime	Description
allow-cross-slot-standalone	boolean	false	—	Allow cross-slot operations in standalone mode. When enabled, multi-key commands like MGET/MSET can operate across different hash slots using scatter-gather. MSETNX always requires same-slot.
bind	string	"127.0.0.1"	✗	Bind address.
max-clients CONFIG: maxclients	integer	10000	✓	Maximum number of simultaneous client connections (0 = unlimited). Admin port connections are exempt from this limit.
num-shards	integer	1	✗	Number of shards (0 = auto-detect CPU cores).
port	integer	6379	✗	Listen port.
scatter-gather-timeout-ms	integer	5000	✓	Timeout for scatter-gather operations in milliseconds.
sorted-set-index	string	"skiplist"	—	Sorted set index backend selection. Options: "btreemap", "skiplist".

Example:

[server]
bind = "127.0.0.1"
port = 6379
num-shards = 0          # auto-detect CPU cores
max-clients = 10000

Persistence

Data durability settings backed by RocksDB.

[persistence]

Option	Type	Default	Runtime	Description
batch-size-threshold-kb	integer	4096	—	Batch size threshold in KB before flushing.
batch-timeout-ms	integer	10	✓	Batch timeout in milliseconds before flushing.
block-cache-size-mb	integer	256	—	RocksDB block cache size in MB.
bloom-filter-bits	integer	10	—	RocksDB bloom filter bits per key. Set to 0 to disable.
compaction-rate-limit-mb	integer	0	—	RocksDB compaction rate limit in MB/s. 0 means unlimited.
compression	string	"lz4"	—	Compression type: "none", "snappy", "lz4", "zstd".
data-dir CONFIG: dir	string	"./frogdb-data"	✗	Directory for data files.
durability-mode	string	"periodic"	✓	Durability mode: "async", "periodic", or "sync".
enabled CONFIG: persistence-enabled	boolean	true	✗	Whether persistence is enabled.
max-write-buffer-number	integer	4	—	Maximum number of RocksDB write buffers.
sync-interval-ms	integer	1000	✓	Sync interval in milliseconds (for periodic mode).
wal-failure-policy	string	"continue"	✓	WAL failure policy: "continue" or "rollback".
write-buffer-size-mb	integer	64	—	RocksDB write buffer size in MB.

Example:

[persistence]
enabled = true
data-dir = "/var/lib/frogdb"
durability-mode = "sync"
compression = "lz4"
block-cache-size-mb = 512

Durability Modes

Mode	Description
async	Writes are buffered and flushed asynchronously. Fastest, but data can be lost on crash.
periodic	Writes are synced at a configurable interval (sync-interval-ms). Good balance of performance and safety.
sync	Every write is synced immediately. Safest, but highest latency.

Snapshot

Point-in-time snapshot settings.

[snapshot]

Option	Type	Default	Runtime	Description
max-snapshots	integer	5	—	Maximum number of snapshots to retain (0 = unlimited).
snapshot-dir	string	"./snapshots"	—	Directory for storing snapshots.
snapshot-interval-secs	integer	3600	—	Interval between automatic snapshots in seconds (0 = disabled).

Example:

[snapshot]
snapshot-dir = "/var/lib/frogdb/snapshots"
snapshot-interval-secs = 1800   # every 30 minutes
max-snapshots = 3

Memory

Memory management and eviction settings.

[memory]

Option	Type	Default	Runtime	Description
doctor-big-key-threshold	integer	1048576	—	Threshold in bytes for MEMORY DOCTOR big key detection. Keys larger than this will be flagged.
doctor-imbalance-threshold	number	25	—	Threshold for shard memory imbalance detection (coefficient of variation). Shards with memory CV higher than this will trigger a warning.
doctor-max-big-keys	integer	100	—	Maximum number of big keys to report per shard in MEMORY DOCTOR.
lfu-decay-time	integer	1	✓	LFU decay time in minutes - counter decays by 1 every N minutes.
lfu-log-factor	integer	10	✓	LFU log factor - higher values make counter increment less likely.
maxmemory	integer	0	✓	Maximum memory limit in bytes. 0 means unlimited. Can use human-readable formats like "100mb", "1gb" in config files.
maxmemory-policy	string	"noeviction"	✓	Eviction policy when maxmemory is reached. Options: noeviction, volatile-lru, allkeys-lru, volatile-lfu, allkeys-lfu, volatile-random, allkeys-random, volatile-ttl
maxmemory-samples	integer	5	✓	Number of keys to sample when looking for eviction candidates.

Eviction Policies

Policy	Description
noeviction	Return error when memory limit is reached.
allkeys-lru	Evict least recently used keys.
allkeys-lfu	Evict least frequently used keys.
allkeys-random	Evict random keys.
volatile-lru	Evict LRU keys with TTL set.
volatile-lfu	Evict LFU keys with TTL set.
volatile-random	Evict random keys with TTL set.
volatile-ttl	Evict keys with shortest TTL.
tiered-lru	Demote LRU keys to warm tier (requires tiered-storage.enabled).
tiered-lfu	Demote LFU keys to warm tier (requires tiered-storage.enabled).

Example:

[memory]
maxmemory = 4294967296   # 4 GB
maxmemory-policy = "allkeys-lru"
maxmemory-samples = 10

Replication

Primary-replica replication settings.

[replication]

Option	Type	Default	Runtime	Description
ack-interval-ms	integer	1000	—	ACK interval - how often replicas send ACKs to primary (milliseconds).
connect-timeout-ms	integer	5000	—	Connection timeout for replica connecting to primary (milliseconds).
fullresync-cooldown-secs	integer	60	—	Cooldown seconds after proactive lag disconnect before allowing another.
fullsync-max-memory-mb	integer	512	—	Maximum memory for full sync buffering (MB). If exceeded, FULLRESYNC requests will be rejected.
fullsync-timeout-secs	integer	300	—	Full sync timeout (seconds). Maximum time to wait for a full sync operation.
handshake-timeout-ms	integer	10000	—	Handshake timeout during replication setup (milliseconds).
min-replicas-timeout-ms CONFIG: min-replicas-max-lag	integer	5000	✓	Timeout for min_replicas_to_write in milliseconds. If replicas don't acknowledge within this time, the write still succeeds but returns with fewer acknowledged replicas.
min-replicas-to-write	integer	0	✓	Minimum replicas required to acknowledge writes (for primary role). If set > 0, writes will wait for this many replicas to acknowledge before returning success.
primary-host	string	""	—	Primary host (for replica role). When role is "replica", this specifies the primary to connect to.
primary-port	integer	6379	—	Primary port (for replica role).
reconnect-backoff-initial-ms	integer	100	—	Reconnection backoff - initial delay (milliseconds).
reconnect-backoff-max-ms	integer	30000	—	Reconnection backoff - maximum delay (milliseconds).
replica-freshness-timeout-ms	integer	3000	—	Freshness timeout for replica ACKs (ms). If no replica ACKs within this window, the primary fences itself. Should be >= 3x ack_interval_ms to tolerate missed ACKs.
replica-write-timeout-ms	integer	5000	—	Write timeout for streaming to replicas (ms). 0 = disabled. Forces TCP disconnect when iptables drops packets.
replication-lag-threshold-bytes	integer	0	—	Max replication lag in bytes before proactive disconnect. 0 = disabled.
replication-lag-threshold-secs	integer	0	—	Max replication lag in seconds (since last ACK) before proactive disconnect. 0 = disabled.
role	string	"standalone"	—	Replication role: "standalone", "primary", or "replica". - standalone: No replication - primary: Accept replica connections - replica: Connect to a primary
self-fence-on-replica-loss	boolean	true	—	Reject writes when primary loses all replica ACK freshness. Prevents zombie writes during network partitions.
split-brain-buffer-max-mb	integer	64	—	Maximum memory in MB for the split-brain command buffer.
split-brain-buffer-size	integer	10000	—	Maximum number of recent commands to buffer for split-brain detection.
split-brain-log-enabled	boolean	true	—	Enable split-brain discarded-writes logging. When a primary is demoted, divergent writes are logged before resync.
state-file	string	"replication_state.json"	—	Replication state file path. Stores replication ID and offset for partial sync recovery.

Example — configuring a replica:

[replication]
role = "replica"
primary-host = "primary.example.com"
primary-port = 6379

Example — configuring a primary with write quorum:

[replication]
role = "primary"
min-replicas-to-write = 1
min-replicas-timeout-ms = 5000

Cluster

Cluster mode settings using Raft consensus.

[cluster]

Option	Type	Default	Runtime	Description
auto-failover	boolean	false	—	Enable automatic failover when a primary fails. When enabled, the leader will automatically promote a replica to primary if the primary becomes unreachable.
client-addr	string	""	—	Address for client connections (host:port). Defaults to server.bind:server.port if not specified.
cluster-bus-addr	string	"127.0.0.1:16379"	—	Address for cluster bus (Raft) communication. Typically server port + 10000 (e.g., 16379 for 6379).
connect-timeout-ms	integer	5000	—	Connection timeout for cluster bus in milliseconds.
data-dir	string	"./frogdb-cluster"	—	Directory for storing cluster state (Raft logs, snapshots).
election-timeout-ms	integer	1000	—	Election timeout in milliseconds. A leader must receive heartbeats within this time or election starts.
enabled	boolean	false	—	Whether cluster mode is enabled.
fail-threshold	integer	5	—	Number of consecutive failures before marking a node as FAIL.
heartbeat-interval-ms	integer	250	—	Heartbeat interval in milliseconds. Leader sends heartbeats at this interval.
initial-nodes	array	[]	—	Initial cluster nodes to connect to (for joining existing cluster). Format: ["host1:port1", "host2:port2"]
node-id	integer	0	—	This node's unique ID (0 = auto-generate from timestamp).
replica-priority	integer	100	—	Priority for replica promotion during auto-failover. Lower values are preferred. 0 means this replica will never be promoted.
request-timeout-ms	integer	10000	—	Request timeout for cluster bus RPCs in milliseconds.
self-fence-on-quorum-loss	boolean	true	—	Reject write commands when this node cannot form a quorum with reachable nodes. When enabled, writes return CLUSTERDOWN if quorum is lost, preventing split-brain data divergence. Reads remain available.

Example:

[cluster]
enabled = true
cluster-bus-addr = "10.0.1.1:16379"
initial-nodes = ["10.0.1.2:16379", "10.0.1.3:16379"]
auto-failover = true

Security

Authentication settings.

[security]

Option	Type	Default	Runtime	Description
requirepass	string	""	—	Legacy password for the default user (like Redis requirepass). If set, clients must AUTH with this password before running commands.

For fine-grained access control, see the ACL section below.

Example:

[security]
requirepass = "your-secure-password"

ACL

Access Control List settings.

[acl]

Option	Type	Default	Runtime	Description
aclfile	string	""	—	Path to the ACL file for SAVE/LOAD operations. If empty, ACL SAVE/LOAD will return an error.
log-max-len	integer	128	—	Maximum number of entries in the ACL LOG.

Logging

Logging configuration.

[logging]

Option	Type	Default	Runtime	Description
file-path	string	—	—	File path for log output. When set, logs are written to this file in addition to console output. Use `output = "none"` to disable console.
format	string	"pretty"	—	Log format (pretty, json).
level CONFIG: loglevel	string	"info"	✓	Log level (trace, debug, info, warn, error).
output	string	"stdout"	—	Console output destination. Options: "stdout", "stderr", "none".
per-request-spans	boolean	false	✓	Enable per-request tracing spans (cmd_read, cmd_execute, cmd_route, etc.). Disabled by default for production performance (~7% CPU savings). Enable for debugging or when distributed tracing is needed.
rotation	string	—	—	Log file rotation settings. Only meaningful when `file_path` is set.

Example:

[logging]
level = "info"
format = "json"
file-path = "/var/log/frogdb/frogdb.log"
output = "none"   # disable console when logging to file

Metrics

Prometheus metrics and OTLP export settings.

[metrics]

Option	Type	Default	Runtime	Description
bind	string	"127.0.0.1"	—	Bind address for the metrics HTTP server.
enabled CONFIG: metrics-enabled	boolean	true	✗	Whether metrics are enabled.
otlp-enabled	boolean	false	—	Whether OTLP export is enabled.
otlp-endpoint	string	"http://localhost:4317"	—	OTLP endpoint URL.
otlp-interval-secs	integer	15	—	OTLP push interval in seconds.
port CONFIG: metrics-port	integer	9090	✗	Port for the metrics HTTP server.

Example:

[metrics]
enabled = true
port = 9090

# Optional: export to an OTLP collector
otlp-enabled = true
otlp-endpoint = "http://otel-collector:4317"
otlp-interval-secs = 30

Admin

HTTP admin API for management operations.

[admin]

Option	Type	Default	Runtime	Description
bind	string	"127.0.0.1"	—	Bind address for the admin RESP protocol listener.
enabled	boolean	false	—	Whether the admin API is enabled.
port	integer	6382	—	Port for the admin RESP protocol listener.

Slow Log

Slow query logging.

[slowlog]

Option	Type	Default	Runtime	Description
log-slower-than CONFIG: slowlog-log-slower-than	integer	10000	✓	Threshold in microseconds. Commands slower than this are logged. Set to 0 to log all commands, -1 to disable logging.
max-arg-len CONFIG: slowlog-max-arg-len	integer	128	✓	Maximum characters per argument before truncation.
max-len CONFIG: slowlog-max-len	integer	128	✓	Maximum number of entries per shard.

Example:

[slowlog]
log-slower-than = 10000   # 10ms in microseconds
max-len = 256

Blocking

Limits for blocking commands (BLPOP, BRPOP, BLMOVE, etc.).

[blocking]

Option	Type	Default	Runtime	Description
max-blocked-connections	integer	50000	—	Maximum total blocked connections (0 = unlimited).
max-waiters-per-key	integer	10000	—	Maximum waiters per key (0 = unlimited).

VLL

Very Lightweight Locking — controls the shard-level locking system.

[vll]

Option	Type	Default	Runtime	Description
lock-acquisition-timeout-ms	integer	4000	—	Timeout for acquiring locks on all shards (ms).
max-continuation-lock-ms	integer	65000	—	Maximum time a continuation lock can be held (ms).
max-queue-depth	integer	10000	—	Maximum queue depth per shard before rejecting new operations.
per-shard-lock-timeout-ms	integer	2000	—	Per-shard lock acquisition timeout (ms).
timeout-check-interval-ms	integer	100	—	Interval for checking/cleaning up expired operations (ms).

JSON

Limits for the JSON data type (JSON.SET, JSON.GET, etc.).

[json]

Option	Type	Default	Runtime	Description
max-depth	integer	128	—	Maximum nesting depth for JSON documents.
max-size	integer	67108864	—	Maximum size in bytes for JSON documents.

Tiered Storage

Two-tier hot/warm storage that demotes values to RocksDB instead of evicting.

[tiered-storage]

Option	Type	Default	Runtime	Description
enabled	boolean	false	—	Enable tiered storage. Requires persistence to be enabled.

Tiered storage requires persistence.enabled = true and a tiered-lru or tiered-lfu eviction policy.

Distributed Tracing

OpenTelemetry-compatible distributed tracing.

[tracing]

Option	Type	Default	Runtime	Description
enabled	boolean	false	—	Whether distributed tracing is enabled.
otlp-endpoint	string	"http://localhost:4317"	—	OTLP endpoint for trace export.
persistence-spans	boolean	false	—	Enable persistence spans (WAL writes, snapshots).
recent-traces-max	integer	100	—	Maximum number of recent traces to retain for DEBUG TRACING RECENT.
sampling-rate	number	1	—	Sampling rate (0.0 to 1.0). 1.0 = sample all, 0.1 = sample 10%.
scatter-gather-spans	boolean	false	—	Enable scatter-gather operation spans (child spans per shard for MGET/MSET).
service-name	string	"frogdb"	—	Service name in traces.
shard-spans	boolean	false	—	Enable shard execution spans (spans inside shard workers).

Example:

[tracing]
enabled = true
otlp-endpoint = "http://jaeger:4317"
sampling-rate = 0.1   # sample 10% of requests

Compatibility

Redis protocol compatibility behavior.

[compat]

Option	Type	Default	Runtime	Description
strict-config	boolean	false	—	When true, CONFIG GET/SET returns errors for Redis params that FrogDB treats as no-ops. When false, silently accepts them for compatibility with Redis clients/tools that set these params.

Status

Health endpoint thresholds used by the status API.

[status]

Option	Type	Default	Runtime	Description
connection-warning-percent	integer	90	—	Threshold percentage for connection warning (0-100).
durability-lag-critical-ms	integer	30000	—	Durability lag critical threshold in milliseconds.
durability-lag-warning-ms	integer	5000	—	Durability lag warning threshold in milliseconds.
memory-warning-percent	integer	90	—	Threshold percentage for memory warning (0-100).

Hot Shard Detection

Thresholds for identifying hot shards in the shard status report.

[hotshards]

Option	Type	Default	Runtime	Description
default-period-secs	integer	10	—	Default period for stats collection in seconds.
hot-threshold-percent	number	20	—	Threshold percentage for "HOT" status.
warm-threshold-percent	number	15	—	Threshold percentage for "WARM" status.

Latency Testing

Startup latency testing and monitoring.

[latency]

Option	Type	Default	Runtime	Description
startup-test	boolean	false	—	Run intrinsic latency test at startup before accepting connections.
startup-test-duration-secs	integer	5	—	Duration of the startup latency test in seconds.
warning-threshold-us	integer	2000	—	Warning threshold for intrinsic latency in microseconds. If max latency exceeds this, a warning is logged.

Latency Bands

SLO-focused latency bucket tracking.

[latency-bands]

Option	Type	Default	Runtime	Description
bands	array	[1,5,10,50,100,500]	—	Latency band thresholds in milliseconds. Requests are counted in cumulative buckets (<=1ms, <=5ms, etc.)
enabled	boolean	false	—	Whether latency band tracking is enabled.

Debug Bundle

Diagnostic bundle generation for troubleshooting.

[debug-bundle]

Option	Type	Default	Runtime	Description
bundle-ttl-secs	integer	3600	—	Bundle TTL in seconds before automatic cleanup.
directory	string	"frogdb-data/bundles"	—	Directory for storing bundles.
max-bundles	integer	10	—	Maximum number of bundles to retain.
max-slowlog-entries	integer	256	—	Maximum slowlog entries to include in bundles.
max-trace-entries	integer	100	—	Maximum trace entries to include in bundles.

MONITOR

Settings for the MONITOR command.

[monitor]

Option	Type	Default	Runtime	Description
channel-capacity	integer	4096	—	Bounded broadcast channel capacity (ring buffer size). Slow subscribers skip ahead rather than blocking the server.

---

Complete Example

# Production configuration

[server]
bind = "0.0.0.0"   # Listen on all interfaces in production
port = 6379
num-shards = 0
max-clients = 10000

[persistence]
enabled = true
data-dir = "/var/lib/frogdb"
durability-mode = "periodic"
sync-interval-ms = 1000
compression = "lz4"

[snapshot]
snapshot-dir = "/var/lib/frogdb/snapshots"
snapshot-interval-secs = 3600
max-snapshots = 5

[memory]
maxmemory = 8589934592   # 8 GB
maxmemory-policy = "allkeys-lru"

[security]
requirepass = "your-secure-password"

[logging]
level = "info"
format = "json"
file-path = "/var/log/frogdb/frogdb.log"

[metrics]
enabled = true
port = 9090

[slowlog]
log-slower-than = 10000
max-len = 256

See Also

frogdb-server Server command-line options

frogctl Operational CLI tool

Deployment Production deployment guide