Configuration Reference

FrogDB is configured with a TOML file. Every table on this page is extracted directly from the Config struct in frogdb-server/crates/config/src/, so its parameter names, types, and defaults match the binary. For the four config surfaces (file, environment variables, CLI flags, CONFIG SET) and their precedence, see Operations → Configuration; this page does not repeat that model.

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/CONFIG SET

Where a field’s CONFIG parameter name differs from its TOML key, it is shown below the TOML key as CONFIG: <name>.

Configuration file format

Pass a TOML file’s path with --config:

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

frogdb.toml

[section]
key = value

Every field below also accepts a FROGDB_-prefixed environment variable and, for a subset of fields, a CLI flag; see Operations → Configuration for the exact mapping and precedence rules.

---

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.
enable-debug-command	boolean	false	—	Enable the DEBUG family of subcommands that are unsafe in production. Currently gates `DEBUG SLEEP`, which parks the connection task for an arbitrary duration and is a trivial denial-of-service vector if exposed to untrusted clients. Default: `false`. The test harness defaults it to `true` so existing test-only DEBUG commands keep working.
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.
flush-compact-range	boolean	true	✗	Reclaim disk eagerly after FLUSHDB/FLUSHALL: follow the range tombstone with an asynchronous DeleteFilesInRange + CompactRange over the cleared column families. Without it, flushed SST bytes are only reclaimed when a compaction happens to cover the range.
max-write-buffer-number	integer	4	—	Maximum number of RocksDB write buffers.
mode	string	"rocksdb"	—	WAL implementation to use: `"rocksdb"` (default, production) or `"fake"` (deterministic in-process sink for simulation tests). `"fake"` requires `enabled = true`.
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).

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-clients	string	"0"	✓	Maximum memory allowed for all client buffers combined. Supports: "0" (disabled), absolute values like "100mb"/"1gb", or a percentage of maxmemory like "5%".
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 an error when the 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 a TTL set.
volatile-lfu	Evict LFU keys with a TTL set.
volatile-random	Evict random keys with a TTL set.
volatile-ttl	Evict keys with the shortest TTL.
tiered-lru	Spill LRU keys to the warm tier instead of deleting them (requires tiered-storage.enabled).
tiered-lfu	Spill LFU keys to the warm tier instead of deleting them (requires tiered-storage.enabled).

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 (log-only). When a demoted primary diverged from the new primary, its divergent writes are logged before resync. This flag controls ONLY that logging; it does not affect cluster behavior. Automatic Role Demotion during failover always runs in cluster mode regardless of this setting — the kill-switch for cluster behavior is `cluster.enabled`, not this flag.
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 a 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

HTTP

Unified HTTP endpoint (default port 9090) serving Prometheus metrics at /metrics and the admin/debug API at /admin/* and /debug/*.

[http]

Option	Type	Default	Runtime	Description
bind	string	"127.0.0.1"	—	Bind address for the HTTP server.
enabled	boolean	true	—	Whether the HTTP server is enabled.
port	integer	9090	—	Port for the HTTP server.
token	string	—	—	Optional bearer token for protected endpoints (/admin/*, /debug/*). When set, requests to these paths must include `Authorization: Bearer `.

Admin

RESP-protocol listener for administrative commands, separate from the main client port.

[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.

TLS

TLS settings for the RESP, admin, HTTP, replication, and cluster-bus listeners.

[tls]

Option	Type	Default	Runtime	Description
ca-file CONFIG: tls-ca-cert-file	string	—	✗	Path to the CA certificate file for client certificate verification (PEM format). Required when `require_client_cert` is not `none`.
cert-file CONFIG: tls-cert-file	string	""	✗	Path to the server certificate file (PEM format).
ciphersuites	array	[]	—	Allowed ciphersuites. Empty means use rustls defaults.
client-cert-file	string	—	—	Path to client certificate for outgoing replication/cluster connections.
client-key-file	string	—	—	Path to client private key for outgoing replication/cluster connections.
enabled	boolean	false	—	Whether TLS is enabled.
handshake-timeout-ms	integer	10000	—	TLS handshake timeout in milliseconds.
key-file CONFIG: tls-key-file	string	""	✗	Path to the server private key file (PEM format).
no-tls-on-admin-port	boolean	true	—	Whether to keep the admin port as plaintext even when TLS is enabled.
no-tls-on-http	boolean	true	—	Whether to keep the HTTP server as plaintext even when TLS is enabled.
protocols CONFIG: tls-protocols	array	["1.3","1.2"]	✗	Allowed TLS protocol versions.
require-client-cert CONFIG: tls-auth-clients	string	"none"	✗	Client certificate authentication mode. Options: "none", "optional", "required".
tls-cluster	boolean	false	✗	Whether to encrypt cluster bus connections.
tls-cluster-migration	boolean	false	—	Whether to enable dual-accept mode for rolling TLS cluster migration.
tls-port	integer	6380	✗	Port for TLS connections.
tls-replication	boolean	false	✗	Whether to encrypt replication connections.
watch-certs	boolean	true	—	Whether to watch certificate files for changes and auto-reload.
watch-debounce-ms	integer	500	—	Debounce interval in milliseconds for certificate file watcher.

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 ACL below.

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.

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]
otlp-enabled = true
otlp-endpoint = "http://otel-collector:4317"
otlp-interval-secs = 30

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.

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 spills values to RocksDB instead of evicting them.

[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).

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.

See also

Configuration surfaces File, env vars, CLI flags, and CONFIG SET precedence

Example config file A complete, generated config file

frogdb-server Server command-line options

frogctl Operational CLI tool