Advanced Configuration

This guide explains every configuration option in plain language.

Use this page when you want to move beyond defaults and tune KalamDB for your workload.

Before You Start

If you are new to setup, start with Getting Started: Configuration.
If you are not sure about a setting, keep the default value first and only tune after observing behavior.
Prefer changing one section at a time, then test.

Focused guides:

Download Full Sample Config

Use this file when you want all available settings documented in one place with comments:

server.example.toml (full commented sample)

Quick download command:


curl -L https://raw.githubusercontent.com/jamals86/KalamDB/refs/heads/main/backend/server.example.toml -o server.sample.toml

Loading Order

Load TOML config file (--config /path/to/server.toml)
Apply environment variable overrides (KALAMDB_*)
Normalize paths and validate configuration

Full Configuration Reference (User-Friendly)

`[server]`

Key	Default	Description
`host`	`"127.0.0.1"`	Network interface to bind. Use `0.0.0.0` to accept remote connections.
`port`	`8080`	HTTP port clients connect to.
`workers`	`0` (auto)	Worker threads for request handling. `0` = auto based on CPU count.
`api_version`	`"v1"`	URL prefix version for API routes.
`enable_http2`	`true`	Enables HTTP/2 support. Keep enabled unless you have proxy compatibility issues.
`ui_path`	`None`	Optional path to Admin UI static files. Leave empty to disable.

`[storage]`

Key	Default	Description
`data_path`	`"./data"`	Base directory where local data is stored. Normalized to absolute path at runtime. Sub-dirs: `rocksdb/`, `storage/`, `snapshots/`, `streams/`.
`shared_tables_template`	`"{namespace}/{tableName}"`	Folder structure template for shared tables.
`user_tables_template`	`"{namespace}/{tableName}/{userId}"`	Folder structure template for user-isolated tables.

`[storage.rocksdb]`

Key	Default	Description
`write_buffer_size`	`2097152` (2 MB)	Memory per write buffer (per column family).
`max_write_buffers`	`2`	Write buffers before flush pressure increases.
`block_cache_size`	`4194304` (4 MB)	Read cache size, shared across all column families.
`max_background_jobs`	`4`	Background compaction/flush workers.
`max_open_files`	`512`	Max open file descriptors. `-1` = unlimited.
`sync_writes`	`false`	Forces WAL fsync on writes. Improves durability but reduces write speed.
`disable_wal`	`false`	Disables write-ahead log. Faster but unsafe for crash recovery.
`compact_on_startup`	`false`	Runs compaction at startup. Helps fragmentation but increases startup time.

`[storage.remote_timeouts]`

Key	Default	Description
`request_timeout_secs`	`60`	Maximum time (seconds) for a remote storage request.
`connect_timeout_secs`	`10`	Maximum time (seconds) to establish a remote connection.

Note: These timeouts apply to standard AWS S3/GCS/Azure only. They are skipped for S3-compatible endpoints (e.g., MinIO) to avoid conflicts.

`[limits]`

Key	Default	Description
`max_message_size`	`1048576` (1 MB)	Maximum incoming payload size accepted by the server.
`max_query_limit`	`1000`	Hard upper bound for `LIMIT` in queries.
`default_query_limit`	`50`	Default `LIMIT` used when query does not specify one.

Validation: max_message_size must be > 0, max_query_limit must be > 0, default_query_limit must be ≤ max_query_limit.

`[logging]`

Key	Default	Description
`level`	`"info"`	Global logging verbosity: `error`, `warn`, `info`, `debug`, `trace`.
`logs_path`	`"./logs"`	Directory where log files are written. Normalized to absolute path at runtime.
`log_to_console`	`true`	Print logs to stdout/stderr in addition to file.
`format`	`"compact"`	Log style: `compact`, `pretty`, `json`. Use `json` in production log pipelines.
`targets`	`{}`	Per-component log level overrides (e.g., `datafusion = "info"` to quiet noisy modules).
`slow_query_threshold_ms`	`1200`	Queries slower than this (ms) are marked/logged as slow.

`[logging.otlp]`

Key	Default	Description
`enabled`	`false`	Turns OpenTelemetry trace export on/off.
`endpoint`	`"http://127.0.0.1:4317"`	OTLP collector endpoint.
`protocol`	`"grpc"`	OTLP transport: `grpc` or `http`.
`service_name`	`"kalamdb-server"`	Name shown in tracing tools (Jaeger/Tempo/etc.).
`timeout_ms`	`3000`	Maximum export timeout (ms) for telemetry batches.

`[performance]`

Key	Default	Description
`request_timeout`	`30`	Max time (seconds) for full request handling.
`keepalive_timeout`	`75`	Idle keep-alive connection timeout (seconds).
`max_connections`	`25000`	Max simultaneous open client connections.
`backlog`	`4096`	Pending TCP connection queue depth.
`worker_max_blocking_threads`	`512`	Limit for blocking tasks per worker.
`client_request_timeout`	`5`	Time (seconds) allowed for client to send request headers.
`client_disconnect_timeout`	`2`	Time (seconds) allowed for graceful client disconnect.
`max_header_size`	`16384` (16 KB)	Max HTTP header size (important for large JWT/cookies).

`[datafusion]`

Key	Default	Description
`memory_limit`	`268435456` (256 MB)	Memory budget for query execution.
`query_parallelism`	`num_cpus` (auto)	Parallel query execution threads.
`max_partitions`	`8`	Upper bound of partitions for query planning.
`batch_size`	`2048`	Record batch size for processing pipelines.

`[flush]`

Key	Default	Description
`default_row_limit`	`10000`	Flush to durable storage after this many rows.
`default_time_interval`	`300` (5 min)	Flush after this many seconds even if row limit is not reached.
`flush_batch_size`	`10000`	Rows processed per batch during flush job.

`[manifest_cache]`

Key	Default	Description
`eviction_interval_seconds`	`300` (5 min)	How often cache cleanup runs.
`max_entries`	`500`	Maximum manifest entries kept in memory.
`eviction_ttl_days`	`7`	Remove entries not accessed within this many days.
`user_table_weight_factor`	`10`	Eviction bias; higher values evict user-table entries sooner (10× default).

`[retention]`

Key	Default	Description
`default_deleted_retention_hours`	`168` (7 days)	Default soft-delete retention window before hard cleanup.

`[stream]`

Key	Default	Description
`default_ttl_seconds`	`10`	Default lifetime (seconds) of stream events.
`default_max_buffer`	`10000`	Max in-memory buffer for stream rows/events.
`eviction_interval_seconds`	`60`	How often expired stream data is removed.

`[websocket]`

Key	Default	Description
`client_timeout_secs`	`10`	Disconnect clients that stop responding past this timeout.
`auth_timeout_secs`	`3`	Time (seconds) allowed to authenticate after opening WebSocket.
`heartbeat_interval_secs`	`5`	Frequency (seconds) for heartbeat checks/pings.

`[rate_limit]`

Key	Default	Description
`max_queries_per_sec`	`100`	Per-user query rate cap.
`max_messages_per_sec`	`50`	Per-WebSocket incoming message rate cap.
`max_subscriptions_per_user`	`10`	Max concurrent subscriptions per user.
`max_auth_requests_per_ip_per_sec`	`20`	Protects login/setup endpoints from brute-force.
`max_connections_per_ip`	`100`	Concurrent socket cap per client IP.
`max_requests_per_ip_per_sec`	`200`	Pre-auth request flood protection per IP.
`request_body_limit_bytes`	`10485760` (10 MB)	Hard cap for request payload body size.
`ban_duration_seconds`	`300` (5 min)	Temporary ban after abuse thresholds exceeded.
`enable_connection_protection`	`true`	Master switch for connection abuse protection.
`cache_max_entries`	`100000`	Max in-memory entries for rate-limiter state.
`cache_ttl_seconds`	`600` (10 min)	Idle expiration for rate-limit cache entries.

`[auth]` (alias: `[authentication]`)

Key	Default	Description
`root_password`	`None`	Optional root password in config file. TOML-only, no env var.
`jwt_secret`	`"CHANGE_ME_IN_PRODUCTION"`	Secret for signing/verifying internal JWTs. Rejected on non-localhost if weak.
`jwt_trusted_issuers`	`""` (empty)	Comma-separated list of trusted token issuers.
`jwt_expiry_hours`	`24`	Internal token expiration lifetime (hours).
`cookie_secure`	`true`	Send auth cookies only over HTTPS.
`min_password_length`	`8`	Minimum accepted user password length.
`max_password_length`	`1024`	Maximum accepted user password length.
`bcrypt_cost`	`12`	Password hash work factor (valid range: 4–31).
`enforce_password_complexity`	`false`	Require mixed character classes in passwords.
`allow_remote_setup`	`false`	Allow first-time setup from non-localhost clients.
`auto_create_users_from_provider`	`false`	Auto-create users on first valid external OIDC token.

`[oauth]`

Key	Default	Description
`enabled`	`false`	Enable OAuth integration settings.
`auto_provision`	`false`	Auto-create matching OAuth users.
`default_role`	`"user"`	Role assigned to auto-provisioned OAuth users.

`[oauth.providers.google]`, `[oauth.providers.github]`, `[oauth.providers.azure]`

Key	Default	Description
`enabled`	`false`	Enable this provider.
`issuer`	`""`	Expected token issuer URL.
`jwks_uri`	`""`	URL to provider public signing keys.
`client_id`	`None`	OAuth app client ID.
`client_secret`	`None`	OAuth app client secret (required for some flows).
`tenant`	`None`	Tenant identifier (mainly used for Azure).

`[user_management]`

Key	Default	Description
`deletion_grace_period_days`	`30`	Days to wait before permanently deleting soft-deleted users. Cannot be negative.
`cleanup_job_schedule`	`"0 2 * * *"`	Cron schedule for user cleanup background task. Cannot be empty.

`[shutdown]`

`[shutdown.flush]`

Key	Default	Description
`timeout`	`300` (5 min)	Maximum wait time (seconds) for flush jobs during graceful shutdown.

`[jobs]`

Key	Default	Description
`max_concurrent`	`10`	Max parallel background jobs.
`max_retries`	`3`	Retry attempts before marking job failed.
`retry_backoff_ms`	`100`	Initial retry delay (ms) between attempts.

`[execution]`

Key	Default	Description
`handler_timeout_seconds`	`30`	Max duration (seconds) for execution handlers.
`max_parameters`	`50`	Max SQL parameters in a request.
`max_parameter_size_bytes`	`524288` (512 KB)	Max size for a single SQL parameter value.
`sql_plan_cache_max_entries`	`1000`	Max cached query plans.
`sql_plan_cache_ttl_seconds`	`900` (15 min)	Idle TTL before cached plans are evicted.

`[security]`

Key	Default	Description
`allowed_ws_origins`	`[]` (falls back to CORS origins)	Allowed origins for WebSocket connections.
`max_ws_message_size`	`1048576` (1 MB)	Max allowed WebSocket message size.
`strict_ws_origin_check`	`false`	If true, rejects WS connections without valid `Origin`.
`max_request_body_size`	`10485760` (10 MB)	Global HTTP request size limit.

`[security.cors]`

Key	Default	Description
`allowed_origins`	`[]` (empty = allow any)	Allowed browser origins for cross-origin requests.
`allowed_methods`	`["GET","POST","PUT","DELETE","PATCH","OPTIONS"]`	Allowed HTTP methods for CORS.
`allowed_headers`	`["Authorization","Content-Type","Accept","Origin","X-Requested-With"]`	Allowed request headers from browsers.
`expose_headers`	`[]`	Response headers exposed to browser JavaScript.
`allow_credentials`	`true`	Allows cookies/authorization with CORS requests.
`max_age`	`3600` (1 hour)	Browser cache duration (seconds) for preflight responses.
`allow_private_network`	`false`	Allow private-network CORS requests where supported.

`[files]`

Key	Default	Description
`max_size_bytes`	`26214400` (25 MB)	Maximum file size per uploaded file.
`max_files_per_request`	`20`	Max files accepted in one request.
`max_files_per_folder`	`5000`	File count threshold before folder rotation.
`staging_path`	`"./data/tmp"`	Temporary path for upload staging.
`allowed_mime_types`	`[]` (empty = allow all)	Restricts MIME types; empty list allows all.

`[cluster]` (optional)

Omit this section entirely for standalone mode.

Key	Default	Description
`cluster_id`	`"cluster"`	Logical identifier for this cluster. Cannot be empty.
`node_id`	(required)	Unique ID (≥ 1) of this node inside the cluster.
`rpc_addr`	`"0.0.0.0:9100"`	Internal Raft RPC address.
`api_addr`	`"0.0.0.0:8080"`	Public/HTTP API address for this node.
`user_shards`	`8`	Number of shards for user table data. Must be > 0.
`shared_shards`	`1`	Number of shards for shared table data. Must be > 0.
`heartbeat_interval_ms`	`250`	Raft leader heartbeat interval (ms).
`election_timeout_ms`	`(500, 1000)`	Min/max timeout range for elections. Min must exceed heartbeat.
`snapshot_policy`	`"LogsSinceLast(1000)"`	Raft snapshot frequency: `"LogsSinceLast(N)"` or `"Never"`.
`max_snapshots_to_keep`	`3`	Snapshots retained on disk. `0` = keep all.
`replication_timeout_ms`	`5000`	Timeout for learner/follower catch-up.
`reconnect_interval_ms`	`3000`	Delay between reconnect attempts to peers. Must be > 0.
`peer_wait_max_retries`	`None`	Max retries waiting for peers during startup.
`peer_wait_initial_delay_ms`	`None`	Initial peer-wait backoff delay.
`peer_wait_max_delay_ms`	`None`	Maximum peer-wait backoff delay.

Total Raft groups = 3 (system metadata + user metadata + jobs) + user_shards + shared_shards.

Validation: node_id > 0, election_timeout_min > heartbeat_interval, election_timeout_max > election_timeout_min, shards > 0, reconnect_interval_ms > 0. If rpc_tls.enabled, all TLS paths are required and each peer must have rpc_server_name.

`[[cluster.peers]]`

Key	Default	Description
`node_id`	—	Peer node unique ID.
`rpc_addr`	—	Peer internal RPC endpoint.
`api_addr`	—	Peer API endpoint.
`rpc_server_name`	`None`	TLS server-name override. Required when TLS is enabled.

`[cluster.rpc_tls]`

Key	Default	Description
`enabled`	`false`	Enable TLS/mTLS on internal cluster RPC.
`ca_cert_path`	`None`	CA certificate used to validate peer certificates. Required when enabled.
`node_cert_path`	`None`	This node’s certificate path. Required when enabled.
`node_key_path`	`None`	Private key path for this node certificate. Required when enabled.

Environment Variable Overrides

Environment variables are helpful in containers and CI/CD, where secrets/hosts/ports differ per environment.

Important: Only certain sections have environment variable overrides. Sections without env var support (e.g., security.*, files.*, oauth.*, websocket.*, stream.*, flush.*, manifest_cache.*, retention.*, jobs.*, execution.*, performance.*, limits.*, datafusion.*, storage.rocksdb.*, storage.remote_timeouts.*, shutdown.*, user_management.*) can only be configured via server.toml.

Boolean Env Var Parsing

Boolean env vars accept "true", "1", or "yes" (case-insensitive) as truthy values.

Exception: KALAMDB_COOKIE_SECURE defaults to true and is only set to false if explicitly "false", "0", or "no".

Common override groups:

KALAMDB_SERVER_HOST, KALAMDB_SERVER_PORT
KALAMDB_LOG_LEVEL, KALAMDB_LOGS_DIR, KALAMDB_LOG_TO_CONSOLE
KALAMDB_OTLP_ENABLED, KALAMDB_OTLP_ENDPOINT, KALAMDB_OTLP_PROTOCOL, KALAMDB_OTLP_SERVICE_NAME, KALAMDB_OTLP_TIMEOUT_MS
KALAMDB_DATA_DIR
KALAMDB_JWT_SECRET, KALAMDB_JWT_TRUSTED_ISSUERS, KALAMDB_JWT_EXPIRY_HOURS, KALAMDB_COOKIE_SECURE, KALAMDB_ALLOW_REMOTE_SETUP
KALAMDB_RATE_LIMIT_AUTH_REQUESTS_PER_IP_PER_SEC
KALAMDB_CLUSTER_ID, KALAMDB_NODE_ID, KALAMDB_CLUSTER_NODE_ID, KALAMDB_CLUSTER_RPC_ADDR, KALAMDB_CLUSTER_API_ADDR, KALAMDB_CLUSTER_PEERS
KALAMDB_CLUSTER_RPC_TLS_ENABLED, KALAMDB_CLUSTER_RPC_TLS_CA_CERT_PATH, KALAMDB_CLUSTER_RPC_TLS_NODE_CERT_PATH, KALAMDB_CLUSTER_RPC_TLS_NODE_KEY_PATH

Legacy variables are still recognized (KALAMDB_HOST, KALAMDB_PORT, KALAMDB_LOG_FILE, KALAMDB_LOG_FILE_PATH, KALAMDB_ROCKSDB_PATH).

Practical Tuning Order

For most user deployments, tune in this order:

auth.jwt_secret, security.cors, rate_limit.* (security first)
storage.data_path, logging.* (operational basics)
performance.*, datafusion.*, flush.* (throughput and latency)
cluster.* only when moving to multi-node deployments

Example: Production-Oriented `server.toml`


[server]
host = "0.0.0.0"
port = 8080
workers = 0
enable_http2 = true
 
[storage]
data_path = "./data"
 
[logging]
level = "info"
format = "json"
logs_path = "./logs"
 
[performance]
max_connections = 25000
 
[auth]
jwt_secret = "REPLACE_WITH_STRONG_SECRET_AT_LEAST_32_CHARS"
cookie_secure = true
enforce_password_complexity = true
 
[rate_limit]
enable_connection_protection = true
max_queries_per_sec = 100
 
[security]
max_request_body_size = 10485760
 
[security.cors]
allowed_origins = ["https://app.example.com"]
allow_credentials = true
 
[files]
max_size_bytes = 26214400

For quick-start defaults and first setup, see Getting Started: Configuration.

Advanced Configuration

Before You Start

Download Full Sample Config

Loading Order

Full Configuration Reference (User-Friendly)

[server]

[storage]

[storage.rocksdb]

[storage.remote_timeouts]

[limits]

[logging]

[logging.otlp]

[performance]

[datafusion]

[flush]

[manifest_cache]

[retention]

[stream]

[websocket]

[rate_limit]

[auth] (alias: [authentication])

[oauth]

[oauth.providers.google], [oauth.providers.github], [oauth.providers.azure]

[user_management]

[shutdown]

[shutdown.flush]

[jobs]

[execution]

[security]

[security.cors]

[files]

[cluster] (optional)

[[cluster.peers]]

[cluster.rpc_tls]