| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_NORMAL_FETCH_SIZE |
500 | A usize | The maximum number of keys that should be scanned at once in general queries. Read only before 3.1.0; later versions use a fixed batch of 500. |
SURREAL_EXPORT_BATCH_SIZE |
1000 | A usize | The maximum number of keys that should be scanned at once for export queries. |
SURREAL_COUNT_BATCH_SIZE_(since v2.2.0)_ |
50,000 (10,000 on 2.x) | A usize | The maximum number of keys that should be scanned at once for count queries. Read only before 3.1.0; later versions use a fixed batch of 50,000. |
SURREAL_INDEXING_BATCH_SIZE |
250 | A usize | The maximum number of keys to scan at once per concurrent indexing batch. Read only before 3.1.0; later versions use a fixed batch of 250. |
SURREAL_TABLE_DOC_IDS_BATCH_SIZE_(since v3.3.0)_ |
1000 | A u32 | The number of document ids allocated at once from a table's shared document id sequence, which full-text, HNSW and DiskANN indexes use. Larger batches reduce coordination on the distributed sequence, at the cost of larger gaps in the ids when a node is lost before it uses up its current batch. Replaces SURREAL_FTS_DOC_IDS_BATCH_SIZE, which 3.3.0 no longer reads. |
SURREAL_GRAPH_FOLD_BATCH_(since v3.3.0)_ |
1024 | A usize | How many graph adjacency keys one background fold pass packs into blocks per transaction. This bounds the transaction size on a vertex with many edges, which is then folded over several passes. See SURREAL_GRAPH_FOLD_INTERVAL. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_TRANSACTION_CACHE_SIZE |
512 (10,000 before 3.1.0) | A usize | Specifies the number of items which can be cached within a single transaction. |
SURREAL_DATASTORE_CACHE_SIZE |
1,000 | A usize | The number of definitions which can be cached across transactions. |
SURREAL_HNSW_CACHE_SIZE |
268,435,456 (256 MiB) | A usize | The maximum total size, in bytes, of the HNSW vector cache, shared across all HNSW indexes in the process. This bounds the cached element vectors used for distance computation - it is not a cap on total HNSW memory: the adjacency graph is loaded into resident memory on first use and stays there, outside this budget. Contrast SURREAL_DISKANN_CACHE_SIZE, which does page graph structure. |
SURREAL_DISKANN_CACHE_SIZE_(since v3.1.0)_ |
268,435,456 (256 MiB) | A usize | The maximum total size, in bytes, of the DISKANN index cache, shared across all DISKANN indexes in the process. DISKANN graph data lives in the key-value store and is paged through this bounded cache. The DISKANN counterpart of SURREAL_HNSW_CACHE_SIZE. |
SURREAL_GRAPH_RESOLVE_CACHE_SIZE_(since v3.3.0)_ |
67,108,864 (64 MiB) | A u64 | The maximum total size, in bytes, of the cache that maps document ids back to record keys when a traversal reads numeric-encoded graph adjacency entries. Only relevant once SURREAL_GRAPH_NUMERIC_IDS has written numeric blocks. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_FILE_ALLOWLIST |
none (deny all) | Colon-separated paths on Unix; semicolon-separated on Windows | Directories the server may read when an analyzer uses mapper('<path>'). An empty or unset value denies every path. Each mapper file must resolve under one of the listed directories. See DEFINE ANALYZER - mapper. |
SURREAL_SEGMENT_DICTIONARY_PATH_(since v3.3.0)_ |
none (use the dictionaries built into the binary) | A path to a directory | Directory holding the morphological dictionaries the segment(<language>) tokenizer reads, one subdirectory per language: chinese, japanese, korean. The released binaries already carry all three, so this is only needed to replace them with a custom or updated dictionary, or for a build made without them. Each language is overridden only if the directory holds a dictionary for it; the rest keep using the built-in one. See DEFINE ANALYZER - segment. |
SURREAL_BUCKET_FOLDER_ALLOWLIST |
none | Comma-separated paths | Specifies a list of paths in which files can be accessed. |
SURREAL_GLOBAL_BUCKET |
none | A string | Specifies the name of a global bucket for file data. |
SURREAL_GLOBAL_BUCKET_ENFORCED |
false | true, false | Whether to enforce a global bucket for file data. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_MAX_HTTP_REDIRECTS |
10 | A usize | The maximum number of HTTP redirects allowed within http functions. |
SURREAL_MAX_HTTP_IDLE_CONNECTIONS_PER_HOST |
128 | A usize | The maximum number of idle HTTP connections to maintain per host. |
SURREAL_MAX_HTTP_IDLE_CONNECTIONS |
1000 | A usize | The maximum number of idle HTTP connections to maintain. Has no effect: earlier versions read the value without applying it to the HTTP client, and 3.3.0 no longer reads it. Use SURREAL_MAX_HTTP_IDLE_CONNECTIONS_PER_HOST instead. |
SURREAL_HTTP_IDLE_TIMEOUT_SECS |
90 | A usize | The timeout for idle HTTP connections before closing. |
SURREAL_HTTP_CONNECT_TIMEOUT_SECS |
30 | A usize | The timeout for connecting to HTTP endpoints. |
SURREAL_SURREALDB_USER_AGENT |
SurrealDB | A string | The USER-AGENT string used by HTTP requests. Before 3.1.0 this variable was named SURREAL_USER_AGENT, which later versions ignore. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_NET_MAX_CONCURRENT_REQUESTS |
1,048,576 | A usize | How many concurrent network requests can be handled at once |
SURREAL_HTTP_MAX_ML_BODY_SIZE |
4,294,967,296 (4 GiB) | A usize | Maximum HTTP body size of the HTTP /ml endpoints. Counted cumulatively across the whole request, not per chunk. |
SURREAL_HTTP_MAX_MCP_BODY_SIZE_(since v3.1.0)_ |
4,194,304 (4 MiB) | A usize | Maximum HTTP body size of the HTTP /mcp endpoint. See [Embedded MCP](/docs/build/ai-agents/mcp/embedded.md). |
SURREAL_HTTP_MAX_SQL_BODY_SIZE |
1,048,576 (1 MiB) | A usize | Maximum HTTP body size of the HTTP /sql endpoint |
SURREAL_HTTP_MAX_GQL_BODY_SIZE_(since v3.2.0)_ |
1,048,576 (1 MiB) | A usize | Maximum HTTP body size of the HTTP /gql endpoint. See GQL via HTTP. |
SURREAL_HTTP_MAX_API_BODY_SIZE |
4,194,304 (4 MiB) | A usize | The maximum HTTP body size of the HTTP /api endpoint. |
SURREAL_HTTP_MAX_RPC_BODY_SIZE |
4,194,304 (4 MiB) | A usize | Maximum HTTP body size of the HTTP /rpc endpoint. |
SURREAL_GRPC_MAX_MESSAGE_SIZE |
The value of SURREAL_HTTP_MAX_RPC_BODY_SIZE, so 4,194,304 (4 MiB) unless that is raised |
A usize, clamped to a ceiling of 4,294,967,295 (4 GiB less one byte), the largest size a gRPC length prefix can express. A value below the floor needed to carry one streaming file chunk is raised to it. | From 3.3.0. The largest single gRPC message the server will accept or emit, also reported to clients as Limits.max_message_bytes. This is the gRPC counterpart of SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE: raise it for a transaction that writes a large batch in one request. |
SURREAL_GRPC_MAX_ATTACHED_SESSIONS_(since v3.3.0)_ |
16384 | A usize | The maximum number of explicitly attached sessions the gRPC transport keeps at once. The count is for the whole process rather than per connection, because a gRPC channel reconnects transparently and one session's requests can arrive on different connections. Per-request sessions do not count towards it. |
SURREAL_GRPC_NOTIFICATION_BUFFER_(since v3.3.0)_ |
1024 | A usize | How many live query notifications can be buffered for a gRPC subscription whose client is not keeping up. When the buffer is full, the server ends that subscription with a RESOURCE_EXHAUSTED status instead of waiting. |
SURREAL_HTTP_MAX_KEY_BODY_SIZE |
16,384 (16 KiB) | A usize | Maximum HTTP body size of the HTTP /key endpoints |
SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE |
1024 (1 KiB) | A usize | Maximum HTTP body size of the HTTP /signup endpoint. |
SURREAL_HTTP_MAX_IMPORT_BODY_SIZE |
4,294,967,296 (4 GiB) | A usize | Maximum HTTP body size of the HTTP /import endpoint. Counted cumulatively across the whole request, not per chunk. Also enforced on the gRPC import stream. See [Request size limits](/docs/reference/rest-api/http-protocol.md#request-size-limits). |
SURREAL_HTTP_MAX_SIGNIN_BODY_SIZE |
1024 (1 KiB) | A usize | The maximum HTTP body size of the HTTP /signin endpoints |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_MCP_QUERY_TIMEOUT_SECS |
60 | Seconds (integer); 0 disables |
Outer timeout on each MCP tool execution. |
SURREAL_MCP_MAX_RESULT_BYTES |
262,144 (256 KiB) | Bytes (integer); 0 disables |
Maximum serialised tool / resource response size; larger results are truncated with a marker. |
SURREAL_MCP_RUN_MAX_ARGS |
64 | A positive integer | Maximum arguments for a single run tool call. |
SURREAL_MCP_PARAMS_MAX_KEYS |
256 | A positive integer | Maximum top-level keys in MCP parameter / data objects. |
SURREAL_MCP_PARAMS_MAX_QL_BYTES |
4,096 (4 KiB) | A positive integer; values ≤ 0 fall back to the default | Maximum byte length of a single $ql SurrealQL pass-through string inside a *_data payload. |
SURREAL_MCP_SCHEMA_RESOURCE_MAX_TABLES |
200 | A positive integer; values ≤ 0 fall back to the default | Maximum tables the database-level schema resource enriches with per-table fields / indexes / events. Tables beyond the cap keep a bare DEFINE TABLE and the body includes a tables_truncated_at marker. |
SURREAL_MCP_ALLOWED_HOSTS _(since v3.2.1)_ |
loopback only (localhost, 127.0.0.1, ::1) |
Comma-separated exact hostnames | Hostnames accepted in the HTTP Host header for /mcp (DNS-rebinding guard). A non-empty list replaces the loopback default, so include localhost yourself if you still need it. Entries without a port match any port. Ignored when SURREAL_MCP_ALLOW_ALL_HOSTS is set. |
SURREAL_MCP_ALLOW_ALL_HOSTS _(since v3.2.1)_ |
false |
true / 1 to enable |
Disables the Host-header allowlist (accept any Host). Escape hatch for a trusted proxy or load balancer. Takes precedence over SURREAL_MCP_ALLOWED_HOSTS. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_GQL_MAX_PATH_ROWS |
1,000,000 | A usize | Per source row, bounds live and emitted rows during variable-length path expansion in a GQL MATCH. |
SURREAL_GQL_MAX_JOIN_BUILD_ROWS |
1,000,000 | A usize | Bounds the in-memory build side of hash joins between GQL match patterns (and distinct-operator working sets). |
SURREAL_GQL_MAX_OUTPUT_ROWS |
1,000,000 | A usize | Bounds cumulative rows emitted by GQL hash-join operators (including cross joins). |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_GRAPH_INLINE_PROPS_CAP _(since v3.3.0)_ |
64 | A number of bytes, without a unit suffix | Largest encoded payload an INLINE field set may occupy inside a graph adjacency entry. A larger payload spills, leaving the values on the edge record only. |
SURREAL_BITMAP_BRANCH_BUDGET_(since v3.3.0)_ |
250,000 | A usize; 0 disables the budget |
How many index entries one range branch of a bitmap plan, which combines several indexes into a bitmap of candidate records, may read before that branch is abandoned. The abandoned branch's condition is then checked as an ordinary WHERE filter, so an unselective range cannot make the bitmap plan slower than scanning. The same budget bounds the allow-list built for a pre-filtered vector search (see Vector search config). |
SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT |
50000 | A usize | The number of result records which will trigger on-disk sorting. |
SURREAL_STRING_SIMILARITY_LIMIT |
16384 | A usize | The maximum input string length for similarity/distance functions |
SURREAL_FAN_OUT_ROW_THRESHOLD_(since v3.3.0)_ |
4 | A usize | A batch with fewer items than this is evaluated one item at a time. A larger batch has its items evaluated concurrently, but only when the evaluation is read-only. Set it above the batch size to turn concurrent evaluation off. |
SURREAL_GENERATION_ALLOCATION_LIMIT |
1,048,576 | A usize | Limits memory allocation for certain built-in functions (e.g., string::replace) to avoid uncontrolled memory usage. Default is 1,048,576 bytes (computed as 220). |
SURREAL_IDIOM_RECURSION_LIMIT |
256 | A usize | The maximum recursive idiom path depth allowed. Read only before 3.1.0; later versions use a fixed limit of 256. |
SURREAL_MAX_COMPUTATION_DEPTH |
120 | A usize | Specifies how deep recursive computation will go before erroring. |
SURREAL_MAX_CONCURRENT_TASKS |
64 | A usize | Specifies how many concurrent jobs can be buffered in the worker channel. |
SURREAL_MAX_EXPRESSION_PARSING_DEPTH_(since v3.3.0)_ |
128 | A usize | How deep the parser will build an expression operator tree. This bounds long operator chains such as 1 + 1 + 1 + … and prefix/postfix chains, which consume neither of the other two parsing budgets. |
SURREAL_MAX_OBJECT_PARSING_DEPTH |
100 | A usize | How deep the parser will parse nested objects and arrays. Type annotations such as array<option<array<int>>> count against it as well. For data arriving over an SDK or RPC this is the governing limit. For a query written as text, see Nesting depth in queries versus data. |
SURREAL_MAX_ORDER_LIMIT_PRIORITY_QUEUE_SIZE_(since v2.2.0)_ |
1000 | A usize | The maximum size of the priority queue triggering usage of the priority queue for the result collector. |
SURREAL_MAX_QUERY_PARSING_DEPTH |
20 | A usize | How deep the parser will parse recursive queries (queries within queries). Object and array literals written into a query count against this budget as well as against SURREAL_MAX_OBJECT_PARSING_DEPTH, and this one is the smaller of the two - see Nesting depth in queries versus data. |
SURREAL_OPERATOR_BUFFER_SIZE |
2 | A usize | The number of batches each operator buffers ahead of downstream demand. Set to 0 to disable operator-level pipeline buffering. |
SURREAL_REGEX_SIZE_LIMIT |
10,485,760 (10 MiB) | A usize | Limits the maximum allowed size (in bytes) for regular expressions. This prevents excessive memory consumption when building complex or very large regex patterns. |
SURREAL_SCAN_BATCH_BYTES_(since v3.3.1)_ |
2,097,152 (2 MiB) | A byte count, or a size such as 512KiB |
The approximate decoded size of each batch of records that a query fetches from an index result, such as the matches of a full-text search. A batch also holds at most 1,000 records. Every operator after the scan holds whole batches, so the memory a query uses grows with this value. Lower it to limit memory on a small node, or raise it for fewer, larger batches. 0 and values that cannot be parsed are ignored. |
SURREAL_TRANSACTION_MAX_WRITE_KEYS_(since v3.2.4)_ |
0 (disabled) | A u64; 0 disables |
Maximum number of key writes a single statement transaction may buffer before it is aborted and rolled back. Cascaded deletes, full-text index maintenance, graph-edge cleanup, and commit-time changefeed / live-query events all count toward the limit; each range delete counts as one write. Tripping the guard poisons the transaction so an explicit client COMMIT cannot persist a partial statement. Internal maintenance transactions (index builds, compaction, GC) are not bounded. On TiKV, range deletes may expand further inside the storage layer - size distributed clusters with both this limit and SURREAL_TIKV_DELR_MAX_KEYS in mind. Scale / multi-node deployments often use a limit in the 50,000-100,000 range; leave at 0 for typical single-node use. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_RUNTIME_MAX_BLOCKING_THREADS |
512 | A usize | Number of threads which can be started for blocking operations. |
SURREAL_RUNTIME_STACK_SIZE |
10,485,760 (10 MiB) | A usize | Runtime thread memory stack size. Default stack size is doubled if compiled from source in Debug mode. |
SURREAL_RUNTIME_WORKER_THREADS |
Number of CPU cores (minimum 4) | A usize | Number of runtime worker threads used to start. See CPU cores and concurrent queries. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_SCRIPTING_MAX_STACK_SIZE |
262_144 (256 KiB) | A usize | Maximum stack size of the JavaScript function runtime. |
SURREAL_SCRIPTING_MAX_MEMORY_LIMIT |
2,097,152 (2 MiB) | A usize | Maximum memory limit of the JavaScript function runtime. |
SURREAL_SCRIPTING_MAX_TIME_LIMIT |
5000 (5000 milliseconds or 5 seconds) | A usize | Maximum allowed time in milliseconds that a JavaScript function is allowed to run for. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_INSECURE_FORWARD_ACCESS_ERRORS |
false | true, false | Forward all signup/signin/authenticate query errors to a client performing authentication. Do not use in production. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_LAZY_SURREALISM_(since v3.1.0)_ |
false | true, false | Whether to lazy-load Surrealism modules instead of eagerly compiling them at server startup. |
SURREAL_SURREALISM_CACHE_SIZE_(since v3.0.0)_ |
100 | A usize | The number of surrealism modules which can be cached across transactions. |
SURREAL_SURREALISM_MAX_POOL_SIZE_(since v3.0.0)_ |
8 | A usize | Per-module controller pool size ceiling for Surrealism WASM modules. Has no effect: the server does not read this variable, so the ceiling stays at 8. |
SURREAL_SURREALISM_MAX_MEMORY_(since v3.0.0)_ |
None (unlimited) | A usize | Per-module WASM linear memory ceiling in bytes. |
SURREAL_SURREALISM_MAX_EXECUTION_TIME_(since v3.0.0)_ |
None (unlimited) | A u64 (milliseconds) | Per-invocation execution time ceiling for Surrealism WASM modules. |
SURREAL_SURREALISM_MAX_KV_ENTRIES_(since v3.0.0)_ |
None (unlimited) | A usize | Per-module KV store entry count ceiling. |
SURREAL_SURREALISM_MAX_KV_VALUE_BYTES_(since v3.0.0)_ |
None (unlimited) | A usize | Per-module KV store maximum value size in bytes. |
SURREAL_SURREALISM_LOG_LEVEL_(since v3.1.0)_ |
debug | none, full, error, warn, info, debug, trace | Controls the tracing level at which Surrealism module stdout is emitted. |
SURREAL_SURREALISM_SILO_ENDPOINT_(since v3.3.0)_ |
https://silo.surrealdb.com |
A URL | The base URL that a silo:: module executable in DEFINE MODULE is fetched from, as {endpoint}/{organisation}/{package}/{major}.{minor}.{patch}.surli. A trailing slash is removed. Set it to a mirror to serve packages from somewhere else. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_TELEMETRY_DISABLE_METRICS |
false | true, false | Whether to disable sending metrics to the GRPC OTEL collector. |
SURREAL_TELEMETRY_DISABLE_TRACING |
false | true, false | Whether to disable sending traces to the GRPC OTEL collector. |
SURREAL_TELEMETRY_NAMESPACE |
none | A string | If set then use this as value for the namespace label when sending telemetry |
SURREAL_TELEMETRY_PROVIDER |
none | otlp | If set to "otlp" then telemetry is sent to the GRPC OTEL collector. |
SURREAL_TOKIO_CONSOLE_ENABLED_(since v3.0.0)_ |
false | true, false | Whether to enable [tokio console](https://github.com/tokio-rs/console). |
SURREAL_TOKIO_CONSOLE_RETENTION_(since v3.0.0)_ |
60 | A usize | How long, in seconds, to retain data for completed events. |
SURREAL_TOKIO_CONSOLE_SOCKET_ADDR_(since v3.0.0)_ |
none | String to a socket address | The socket address that Tokio Console will bind to. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_KNN_PREFILTER_ENABLED |
true | true, false | Whether KNN queries build an allow-list from their WHERE conditions. When false, the conditions are checked for each candidate during the index traversal instead, as before 3.3.0. |
SURREAL_KNN_PREFILTER_EXACT_THRESHOLD |
2000 | A u64 | The allow-list size at or below which the search does not use the index graph at all, and instead scores every allowed record exactly. At this size an exact search is cheaper than a traversal and always finds the true nearest neighbours. |
SURREAL_KNN_PREFILTER_EF_BOOST |
4 | A u32 | The multiplier applied to the search width (ef) of a traversal restricted to an allow-list. A selective allow-list rejects most candidates, and a wider search recovers the recall that loses. The result is capped by SURREAL_KNN_PREFILTER_EF_MAX and is never lower than the ef the query asks for. |
SURREAL_KNN_PREFILTER_EF_BOOST_THRESHOLD |
100,000 | A u64 | The allow-list size above which the traversal stops multiplying ef, because a large allow-list rejects few candidates. Results are still restricted to the allow-list at every size. |
SURREAL_KNN_PREFILTER_EF_MAX |
1024 | A u32 | The ceiling for the multiplied ef. It never lowers the ef a query asks for. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE |
134,217,728 (128 MiB) | A usize | The maximum WebSocket message size, which is also used as the maximum frame size. From 3.0.0 this replaces SURREAL_WEBSOCKET_MAX_FRAME_SIZE, which no longer exists and has no effect if set. |
SURREAL_WEBSOCKET_MAX_WRITE_BUFFER_SIZE |
Greatest possible usize value | A usize | The maximum write buffer size before backpressure is applied. |
SURREAL_WEBSOCKET_READ_BUFFER_SIZE |
131,072 (128 KiB) | A usize | The size of the read buffer for WebSocket connections. This controls how much data can be buffered when reading from WebSocket connections. Larger values can improve performance for high-throughput connections but consume more memory per connection. |
SURREAL_WEBSOCKET_WRITE_BUFFER_SIZE |
131,072 (128 KiB) | A usize | The size of the write buffer for WebSocket connections. This controls how much data can be buffered when writing to WebSocket connections. Larger values can improve performance for high-throughput connections but consume more memory per connection. |
SURREAL_WEBSOCKET_RESPONSE_BUFFER_SIZE |
0 | A usize | How many responses can be buffered when delivering to the client. |
SURREAL_WEBSOCKET_RESPONSE_CHANNEL_SIZE |
100 | A usize | Number of messages that can be queued for sending via WebSocket. From 3.3.0, replies and live query notifications have separate queues on each connection, each holding this many messages, and a value below 2 is raised to 2. A connection whose notification queue is full is closed, with a close frame giving the reason, rather than dropping notifications. |
SURREAL_WEBSOCKET_RESPONSE_FLUSH_PERIOD |
3 | A usize | How often (in milliseconds) any buffered responses are flushed to the WebSocket client. |
SURREAL_WEBSOCKET_MAX_CONCURRENT_STREAMS_(since v3.3.0)_ |
32 | A usize | Maximum number of streaming queries (the query_stream RPC method) running at once on a single WebSocket connection. Each open stream holds an executing query, with its read snapshot or transaction, for as long as the client keeps reading. A request over the limit is refused with an error rather than queued. |
SURREAL_WEBSOCKET_STREAM_SEND_TIMEOUT_(since v3.3.0)_ |
30 | Seconds (integer), clamped to 1-86,400 | How long a streaming query may wait to hand one frame to the connection before the stream is stopped. The wait resets for every frame, so it limits a stalled client rather than the length of a stream, and it applies even when SURREAL_QUERY_TIMEOUT is not set. |
SURREAL_MAX_TRANSACTIONS_PER_CONNECTION_(since v3.2.2)_ |
64 | A usize | Maximum concurrently open client-managed transactions (begin RPC) on a WebSocket connection's implicit default session. Further begin calls return Too many open transactions until a slot is freed by commit, cancel, reset, or disconnect. Does not apply to attached sessions (see SURREAL_MAX_TRANSACTIONS_PER_SESSION). |
SURREAL_MAX_TRANSACTIONS_PER_SESSION_(since v3.2.2)_ |
64 | A usize | Maximum concurrently open client-managed transactions within a single attached WebSocket session. Counted per session and independent of the connection default-session limit. Detaching or resetting a session cancels its open transactions and frees their slots. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_RAND_SEED |
none (non-deterministic) | A u64 |
Seeds the engine-wide RNG for reproducible runs in benchmarks and tests. Do not use in production. |
SURREAL_LIVE_QUERY_ENGINE |
inline |
inline, router |
Selects the live-query execution engine. inline is the historical behaviour; router decouples write cost from subscriber count (experimental rollout). |
SURREAL_LIVE_QUERY_RETENTION |
1h | A duration | How long the router engine retains live-query event history for subscriber resume. Only applies when SURREAL_LIVE_QUERY_ENGINE=router. |
SURREAL_HNSW_BUILD_SEED |
none | A u64 |
Seeds HNSW index construction for reproducible graph layouts in benchmarks. Do not use in production. |
SURREAL_GRAPH_NUMERIC_IDS_(since v3.3.0)_ |
false | true, false | Whether background graph folds write numeric-encoded adjacency blocks, which store each entry's record id as a compact table-level document id. Existing blocks are converted on their next fold, and reads handle both encodings. Size the lookup cache with SURREAL_GRAPH_RESOLVE_CACHE_SIZE. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_BUILD_METADATA |
Automatically populated | A string | The version identifier of this build. Defaults to the CARGO_PKG_VERSION environment variable if not specified. |
SURREAL_DATASTORE_AOL_(since v3.0.0)_ |
never | never|sync|async | Append-only log mode. Only used by the memory engine. |
SURREAL_DATASTORE_PERSIST_(since v3.0.0)_ |
none | String to a file path | Filesystem path for persistence. Only used by the memory engine. |
SURREAL_DATASTORE_RETENTION_(since v3.0.0)_ |
0 (unlimited) | A duration | Version retention period as a duration string. Used by the rocksdb and surrealkv engines. From 3.3.0 the memory engine refuses a non-zero value and the server does not start. _(since v3.3.0)_ |
SURREAL_DATASTORE_SNAPSHOT_(since v3.0.0)_ |
never | never|duration | Snapshot interval. Only used by the memory engine. |
SURREAL_DATASTORE_SYNC_DATA_(since v3.0.0)_ |
every | never|every|duration | The sync mode for the database. Used by memory, rocksdb, and surrealkv engines. |
SURREAL_DATASTORE_VERSIONED_(since v3.0.0)_ |
false | true|false|0|1 | Whether MVCC versioning is enabled, for use with the VERSION clause. Used by the rocksdb and surrealkv engines. From 3.3.0 the memory engine does not support versioned queries, and refuses true so that the server does not start. _(since v3.3.0)_ |
SURREAL_MEMORY_THRESHOLD |
0 (disabled) | A usize or suffixed integer | The tracked memory, in bytes, above which queries are refused with The query was not executed due to the memory threshold being reached. The value can be specified as bytes (b, or without any suffix), kibibytes (k, kb, or kib), mebibytes (m, mb, or mib), or gibibytes (g, gb, or gib); Kubernetes-style Gi and Mi are not accepted. Unset or 0 disables the guard, and any other value is raised to at least 1 MiB. Tracked memory is the size the allocator reserves for each live heap allocation plus the RocksDB block cache, which is less than the process's resident memory, so set the threshold below the container's memory limit and above SURREAL_ROCKSDB_BLOCK_CACHE_SIZE: at or below the cache size, a full cache refuses every query until the server restarts. From 3.3.0 the reserved size rather than the requested size is counted, so a threshold carried over from an earlier release refuses queries at a lighter workload and may need raising. _(since v3.3.0)_ From 3.3.1 the threshold also stops a query that is already running: a query that reads records checks it after each batch, and fails with the same error once tracked memory is above it, rather than growing until the operating system stops the server. _(since v3.3.1)_ |
SURREAL_REGEX_CACHE_SIZE |
1000 | A usize | The number of computed regexes which can be cached in the engine. |
| Environment variable | Command arg | For command(s) | Default | Allowed values | Details |
|---|---|---|---|---|---|
SURREAL_ASYNC_EVENT_PROCESSING_INTERVAL_(since v3.0.0)_ |
async-event-interval |
`start` | 5s | A duration | The interval at which to process async events. |
SURREAL_AUTH_LEVEL |
auth-level |
`export`, `import`, `sql` | root | root, namespace, ns, database, db | Authentication level to use when connecting. |
SURREAL_BIND |
bind |
`start` | 127.0.0.1:8000 | String to an address | The hostname or IP address(es) to listen for connections on. |
SURREAL_POSTGRES_BIND |
postgres-bind |
`start` | (disabled) | String to an address | The hostname or IP address to listen for Postgres wire protocol connections on. |
SURREAL_CAPS_ALLOW_ALL |
allow-all |
`start` | false | true, false | Allow all capabilities. |
SURREAL_CAPS_ALLOW_ARBITRARY_QUERY |
allow-arbitrary-query |
`start` | none | guest, record, system (comma-separated) | Allows arbitrary queries to be used by user groups except when specifically denied. Alternatively, you can provide a comma-separated list of user groups to allow specifically denied user groups to prevail over any other allowed user group. |
SURREAL_CAPS_ALLOW_EVAL_QUERY_(since v3.2.0)_ |
allow-eval-query |
`start`, `sql` | none (denied for all subjects) | guest, record, system (comma-separated) | Allow eval::surql and eval::gql for listed subject groups. Not enabled by --allow-all. Still subject to arbitrary-query restrictions - --deny-arbitrary-query blocks eval for that subject even when eval is allowed here. For remote clients, set on the start process only. See Capabilities and remote connections. |
SURREAL_CAPS_ALLOW_EXPERIMENTAL |
allow-experimental |
`start`, `sql` | none | files, surrealism (comma-separated; legacy gql accepted but unused from 3.3.0) |
Allow execution of experimental features. For remote clients, set on the start process. On surreal db sql, affects embedded engines and REPL parse validation only. See experimental capabilities. From 3.3.0, ISO GQL (Cypher Query Language) is on by default and does not need this variable. |
SURREAL_CAPS_ALLOW_FUNC |
allow-funcs |
`start` | all functions allowed | Empty, *, or comma-separated function paths |
Allow execution of all functions except for functions that are specifically denied. Set to an empty value or * to allow all functions. Use a comma-separated list (for example, array,string::len,http::get) to allow specific function families or names. Values such as true are not valid. The environment variable name is singular (FUNC), matching the --allow-funcs flag. |
SURREAL_CAPS_ALLOW_GUESTS |
allow-guests |
`start` | false | true, false | Allow guest users to execute queries. |
SURREAL_CAPS_ALLOW_NET |
allow-net |
`start` | none | Comma-separated list of paths | Allow all or certain outbound network access. |
SURREAL_CAPS_ALLOW_SCRIPT |
allow-scripting |
`start` | false | true, false | Allow execution of embedded scripting functions. |
SURREAL_CAPS_ALLOW_INSECURE_STORABLE_CLOSURES_(since v2.5.0)_ |
allow-insecure-storable-closures |
`start` | false | true, false | Takes a boolean. From 2.5.0, closures cannot be stored, which removes a potential attack surface; on 2.5.x and 2.6.x this capability allows them again. Removed in 3.0.0, where closures can never be stored and the flag is rejected. |
SURREAL_CAPS_DENY_ALL |
deny-all |
`start` | false | true, false | Deny all capabilities. |
SURREAL_CAPS_DENY_EVAL_QUERY_(since v3.2.0)_ |
deny-eval-query |
`start`, `sql` | none | guest, record, system (comma-separated) | Deny eval::surql and eval::gql for listed subject groups. Deny prevails over allow at the same specificity. For remote clients, set on the start process. |
SURREAL_CAPS_DENY_FUNC |
deny-funcs |
`start` | false | true, false, comma-separated list | Deny execution of all or certain functions. |
SURREAL_CAPS_DENY_GUESTS |
deny-guests |
`start` | true | true, false | Deny guest users from executing queries. |
SURREAL_CAPS_DENY_NET |
deny-net |
`start` | true | true, false, comma-separated list | Deny all or certain outbound access paths. |
SURREAL_CAPS_DENY_SCRIPT |
deny-scripting |
`start` | true | true, false | Deny execution of embedded scripting functions. |
SURREAL_CHANGEFEED_GC_INTERVAL |
changefeed-gc-interval |
`start` | 30s | A duration | The interval at which to perform changefeed garbage collection. |
SURREAL_CLIENT_IP |
client-ip |
`start` | none | none, socket, CF-Connecting-IP, Fly-Client-IP, True-Client-IP, X-Real-IP, X-Forwarded-For, Forwarded | The method of detecting the client's IP address. _(since v3.1.0)_ Forwarded parses the RFC 7239 Forwarded header (for= parameter). |
SURREAL_DATABASE |
database |
`sql` | main | A string | The database selected when starting the REPL. |
SURREAL_DATABASE |
database |
`export`, `import` | none | A string | The database selected for the import or export. |
SURREAL_DEFAULT_DATABASE_(since v3.0.0)_ |
default-database |
`start` | main | A string | The default database to use when starting a SurrealDB instance. |
SURREAL_DEFAULT_NAMESPACE_(since v3.0.0)_ |
default-namespace |
`start` | main | A string | The default namespace to use when starting a SurrealDB instance. |
SURREAL_DURABLE_SESSIONS_(since v3.2.2)_ |
durable-sessions |
`start` | false | true, false | Persist client-attached HTTP RPC sessions in the datastore so they survive restarts and can be resumed on any node sharing the storage. Off by default. WebSocket sessions are not durable. The persisted copy includes authentication state and is stored unencrypted. See Durable HTTP RPC sessions. |
SURREAL_DURABLE_SESSION_GC_INTERVAL_(since v3.2.2)_ |
durable-session-gc-interval |
`start` | 60s | A duration; 0 disables the background sweep |
How often expired durable HTTP RPC sessions are purged. Lazy expiry on load still applies when the sweep is disabled. Only meaningful when durable sessions are enabled. |
SURREAL_DURABLE_SESSION_TTL_(since v3.2.2)_ |
durable-session-ttl |
`start` | 24h | A duration greater than zero | Idle lifetime of a persisted HTTP RPC session; each use refreshes the expiry (sliding TTL). Must be greater than zero when durable sessions are enabled. |
SURREAL_GRAPH_FOLD_INTERVAL_(since v3.3.0)_ |
graph-fold-interval |
`start` | 5s | A duration | The interval between background passes that fold a vertex's per-edge graph adjacency keys into packed blocks. A pass also starts early when a write queues fold work or a traversal meets a vertex with many unfolded keys. See also SURREAL_GRAPH_FOLD_BATCH. |
SURREAL_HIDE_WELCOME |
hide-welcome |
`sql` | false | true, false | Whether to show the welcome message when starting the REPL. |
SURREAL_IMPORT_FILE |
import-file |
`start` | none | A file path | Path to a SurrealQL file that will be imported when starting the server. |
SURREAL_INDEX_COMPACTION_INTERVAL_(since v3.0.0)_ |
index-compaction-interval |
`start` | 5s | A duration | The interval at which to compact queued index updates. Writes to a full-text, count, or vector index enqueue pending updates that a background task folds into the index; this controls how often that task runs. One node in a cluster performs the work for the whole cluster. Lengthening the interval allows the pending backlog to grow, which increases the work each subsequent query must do to read through it. |
SURREAL_KEY |
key |
`start` | none | A string 16, 24, or 32 bytes long | Encryption key to use for on-disk encryption. Not currently in use. |
SURREAL_KVS_CA |
kvs-ca |
`start` | none | String to a path | Path to the CA file used when connecting to the remote KV store. |
SURREAL_KVS_CRT |
kvs-crt |
`start` | none | String to a path | Path to the certificate file used when connecting to the remote KV store. |
SURREAL_KVS_KEY |
kvs-key |
`start` | none | String to a path | Path to the private key file used when connecting to the remote KV store. |
SURREAL_LAZY_SURREALISM_(since v3.1.0)_ |
lazy-surrealism |
`start` | false | true, false | Whether to lazy-load Surrealism modules instead of eagerly compiling them at server startup. |
SURREAL_LOG |
log |
`start`, `fix` | info | none, full, error, warn, info, debug, trace | The logging level for the database server. |
SURREAL_LOG_FILE_ENABLED_(since v2.4.0)_ |
log-file-enabled |
`start` | false | true, false | Toggles file output. |
SURREAL_LOG_FILE_FORMAT_(since v2.4.0)_ |
log-file-format |
`start` | none | text, json | The format for log file output. |
SURREAL_LOG_FILE_LEVEL_(since v2.4.0)_ |
log-file-level |
`start` | none | none, full, error, warn, info, debug, trace | Override the logging level for file output |
SURREAL_LOG_FILE_NAME_(since v2.4.0)_ |
log-file-name |
`start` | surrealdb.log | String to a file | Filename for logs (default: `surrealdb.log`) |
SURREAL_LOG_FILE_PATH_(since v2.4.0)_ |
log-file-path |
`start` | logs | String to a path | Sets the directory for logs |
SURREAL_LOG_FILE_ROTATION_(since v2.4.0)_ |
log-file-rotation |
`start` | daily | daily, hourly, never | Sets the rotation duration for logs. |
SURREAL_LOG_FORMAT_(since v2.4.0)_ |
log-format |
`start` | text | text, json | Sets the format for logs. |
SURREAL_LOG_OTEL_LEVEL_(since v2.4.0)_ |
log-otel-level |
`start` | SURREAL_LOG logging level | none, full, error, warn, info, debug, trace | Override the logging level for OpenTelemetry |
SURREAL_LOG_SOCKET_(since v3.0.0)_ |
log-socket |
`start` | none | String to a host:port | Send logs to the specified host:port |
SURREAL_LOG_SOCKET_FORMAT_(since v3.0.0)_ |
log-socket-format |
`start` | text | text, json | Set the format of the logs to the socket. |
SURREAL_LOG_SOCKET_LEVEL_(since v3.0.0)_ |
log-socket-level |
`start` | SURREAL_LOG logging level | none, full, error, warn, info, debug, trace | Override the logging level for socket logs. Possible values: none, full, error, warn, info, debug, trace |
SURREAL_NAME |
name |
`ml export` | none | A string | The name of the model. |
SURREAL_NAMESPACE |
namespace |
`sql` | main | A string | The namespace to connect to via the REPL. |
SURREAL_NAMESPACE |
namespace |
`export`, `import` | none | A string | The namespace selected for the import/export operation. |
SURREAL_NO_BANNER |
no-banner |
`start` | false | true, false | Whether to hide the startup banner. |
SURREAL_NO_DEFAULTS_(since v3.0.0)_ |
no-defaults |
`start` |
false | true, false | Whether to disable default namespace and database creation. Conflicts with SURREAL_DEFAULT_DATABASE and SURREAL_DEFAULT_NAMESPACE, which set a default value for namespace and database for a new instance. |
SURREAL_NO_IDENTIFICATION_HEADERS |
no-identification-headers |
`start` | false | true, false | Whether to suppress the server name and version headers. |
SURREAL_NODE_MEMBERSHIP_CHECK_INTERVAL |
node-membership-check-interval |
`start` | 15s | A duration | The interval at which to process and archive inactive nodes. |
SURREAL_NODE_MEMBERSHIP_CLEANUP_INTERVAL |
node-membership-cleanup-interval |
`start` | 300s | A duration | The interval at which to process and cleanup archived nodes. |
SURREAL_NODE_MEMBERSHIP_REFRESH_INTERVAL |
node-membership-refresh-interval |
`start` | 3s | A duration | The interval at which to refresh node registration information. The /ready endpoint reports the node unhealthy when its cluster heartbeat is older than three times this interval (9s by default). The multiple is fixed and cannot be configured. |
SURREAL_PASS |
pass |
`export`, `import`, `sql`, `start` | none | A string | Database authentication password to use when connecting. |
| SURREAL_PATH | path |
`fix`, `start` | memory | A string | Database path used for storing data. As a required argument (albeit with a default), it is not passed in via `--path`. |
SURREAL_PLANNER_STRATEGY_(since v3.0.0)_ |
planner-strategy |
`start` | best-effort | best-effort|compute-only|all-read-only | Which strategy to use with the new query planner introduced in SurrealDB 3.0. The default setting uses the new planner for read-only statements, falling back to the previous compute planner on unimplemented paths. The new planner can be skipped entirely by using compute-only. |
SURREAL_QUERY_TIMEOUT |
query-timeout |
`start` | none | A duration | The maximum duration that a batch of statements can run for. From 3.3.0 it is also a hard wall-clock limit on each HTTP /sql, /gql and /graphql request and on each RPC method call. An HTTP /sql or /gql request that exceeds it is answered with 504 Gateway Timeout, and a /graphql request with a GraphQL error. The begin, commit and cancel RPC methods are exempt, but the calls made inside the transaction they control are still limited individually. _(since v3.3.0)_ |
SURREAL_RECLAIM_INTERVAL_(since v3.2.0)_ |
reclaim-interval |
`start` | 60s | A duration | How often the background reaper scans for tombstoned namespace, database, and index data to physically delete after a REMOVE statement. On the 2.x line it is available from 2.7.0 and covers namespaces and databases only. |
SURREAL_RECLAIM_GRACE_(since v3.2.0)_ |
reclaim-grace |
`start` | 10m | A duration | Minimum age a removed namespace, database, or index must reach before its data is reclaimed. The effective grace is the maximum of this value and --tikv-gc-lifetime on TiKV backends. Not available on 2.x. |
SURREAL_SLOW_QUERY_LOG_THRESHOLD_(since v2.3.8)_ |
slow-log-threshold |
`start` | none | A duration | A duration specifying the minimum execution time after which a log is made to indicate a slow query |
SURREAL_SLOW_QUERY_LOG_PARAM_ALLOWslow-log-param-allow _(since v2.3.9)_ |
slow-log-param-allow |
`start` | none | Comma-separated strings | A comma-separated list of parameter names to include in slow query logs. |
SURREAL_SLOW_QUERY_LOG_PARAM_DENY_(since v2.3.9)_ |
slow-log-param-deny |
`start` | none | Comma-separated strings | A comma-separated list of parameter names to omit from slow query logs. |
SURREAL_STRICT |
strict |
`start` | false | true, false | Whether strict mode is enabled on this database instance. Ignored since SurrealDB 3.0 after which strictness is defined [per database](/docs/reference/query-language/statements/define/database.md#defining-a-strict-database) instead of instance. |
SURREAL_STARTUP_OPERATION_TIMEOUT |
startup-operation-timeout |
`start` | 60s | A duration | How long each built-in startup datastore operation may keep retrying before the server gives up. It is a per-operation budget rather than a total for startup, and it covers initialising the default namespace and database, initialising the root credentials, and registering this node in the cluster. Raise it where the storage backend is slow to accept the first writes. |
SURREAL_TEMPORARY_DIRECTORY |
temporary-directory |
`start` | none | String to a directory | Sets the directory for storing temporary database files |
SURREAL_TOKEN |
token |
`export`, `import`, `sql` | none | A string | Authentication token in JWT format to use when connecting. |
SURREAL_TRANSACTION_TIMEOUT |
transaction-timeout |
`start` | none | A duration | The maximum duration that any single transaction can run for. |
SURREAL_UNAUTHENTICATED |
unauthenticated |
`start` | false | true, false | Whether to allow unauthenticated access. |
SURREAL_USER |
user |
`export`, `import`, `sql`, start | none | A string | Database authentication username to use when connecting. |
SURREAL_VERSION |
version |
`ml export` | none | A string | The version of the ML model. |
SURREAL_WEB_CRT |
web-crt |
`start` | none | String to a path | Path to the certificate file for encrypted client connections. |
SURREAL_WEB_KEY |
web-key |
`start` | none | String to a path | Path to the private key file for encrypted client connections. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_HTTP_AUTH_RATE_LIMIT_ENABLED |
false | true, false | Whether to rate limit authentication attempts on the HTTP /signin and /signup endpoints per client address. Only true and false are accepted; any other value is ignored and the default applies. |
SURREAL_HTTP_AUTH_RATE_LIMIT_BURST |
60 | A u32 | How many authentication attempts a single client address may make before being throttled. Set to 0 to disable the limiter. |
SURREAL_HTTP_AUTH_RATE_LIMIT_PER_MINUTE |
60 | A u32 | The sustained rate, in attempts per minute, at which a client address's budget refills. The default of 60 is one attempt per second. Set to 0 to disable the limiter. |
SURREAL_HTTP_AUTH_RATE_LIMIT_MAX_TRACKED_CLIENTS |
16384 | A usize | How many client addresses the limiter tracks at once. Unauthenticated callers write to this store, so it is a bounded cache: at capacity a new address evicts an existing entry rather than the store growing or the limiter switching off. An evicted address starts again from a full burst, so the sustained rate binds an address only while it stays tracked. Size this above the number of distinct addresses the instance authenticates. Set to 0 to disable the limiter. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_ROCKSDB_BACKGROUND_FLUSH |
true | false, true | Whether to enable background WAL file flushing. 2.x only: from 3.0.0, set a duration on SURREAL_DATASTORE_SYNC_DATA instead. |
SURREAL_ROCKSDB_BACKGROUND_FLUSH_INTERVAL |
200 (milliseconds) | A usize | The interval in milliseconds between background flushes. 2.x only: from 3.0.0, set a duration on SURREAL_DATASTORE_SYNC_DATA instead. |
SURREAL_ROCKSDB_BLOB_COMPACTION_READAHEAD_SIZE |
0 | A usize | Readahead size for blob compaction/GC. |
SURREAL_ROCKSDB_BLOB_COMPRESSION_TYPE |
snappy | none, snappy, lz4, zstd | Compression type used for blob files. |
SURREAL_ROCKSDB_BLOB_FILE_SIZE |
268,435,456 (256 MiB) | A usize | The target blob file size for RocksDB. |
SURREAL_ROCKSDB_BLOB_GC_AGE_CUTOFF |
0.5 | Float between 0 and 1 | Fractional age cutoff for blob GC. |
SURREAL_ROCKSDB_BLOB_GC_FORCE_THRESHOLD |
0.5 | Float between 0 and 1 | Discardable ratio threshold to force GC. |
SURREAL_ROCKSDB_BLOCK_CACHE_SIZE |
Dynamically calculated via greater of ((system memory / 2) - 1 GiB) and 16MiB | A usize | RocksDB block cache size in bytes |
SURREAL_ROCKSDB_BLOCK_SIZE |
65,536 (64 KiB) | A usize | The size of each uncompressed data block in bytes. |
SURREAL_ROCKSDB_COMPACTION_READAHEAD_SIZE |
4 MiB (systems under 4 GiB), 8 MiB (up to 16 GiB), 16 MiB (others) | A usize | The readahead buffer size used during compaction. |
SURREAL_ROCKSDB_COMPACTION_STYLE |
level | level, universal | Use to specify the database compaction style. |
SURREAL_ROCKSDB_COMPACT_ON_SHUTDOWN_(since v3.1.0)_ |
false | true, false | Whether a graceful shutdown runs a full compaction of the database after flushing the memtables, as ALTER SYSTEM COMPACT does. On a large database this can take minutes or hours, which can be longer than the shutdown grace period of a container orchestrator. |
SURREAL_ROCKSDB_DELETION_FACTORY_DELETE_COUNT |
50 | A usize | The number of deletions to track in the window. |
SURREAL_ROCKSDB_DELETION_FACTORY_RATIO |
0.5 | A float | The ratio of deletions to track in the window. |
SURREAL_ROCKSDB_DELETION_FACTORY_WINDOW_SIZE |
1000 | A usize | The size of the window used to track deletions. |
SURREAL_ROCKSDB_ENABLE_BLOB_FILES |
true | true, false | Whether to enable separate key and value file storage. |
SURREAL_ROCKSDB_ENABLE_BLOB_GC |
true | true, false | Whether to enable blob garbage collection for RocksDB. |
SURREAL_ROCKSDB_ENABLE_PIPELINED_WRITES |
true | true, false | Whether to use separate queues for WAL writes and memtable writes. |
SURREAL_ROCKSDB_FILE_COMPACTION_TRIGGER |
4 | A usize | The number of files needed to trigger level 0 compaction. |
SURREAL_ROCKSDB_FILE_READS_FOR_AUTO_READAHEAD_(since v3.1.0)_ |
2 | A u64 | The number of sequential reads an iterator makes on one SST file before RocksDB starts to prefetch. Set to 0 to prefetch from the first read. |
SURREAL_ROCKSDB_GROUPED_COMMIT_MAX_BATCH_SIZE |
4096 | A usize | The maximum number of transactions in a single grouped commit batch. Used to prevent unbounded memory growth while still allowing large batches for efficiency. Larger batches improve throughput but increase memory usage and commit latency. |
SURREAL_ROCKSDB_GROUPED_COMMIT_TIMEOUT |
5ms | A duration | The maximum wait time in nanosecond before forcing a grouped commit. Used to ensure that transactions do not wait indefinitely when concurrency is low, and to balance between transaction latency and write throughput. |
SURREAL_ROCKSDB_GROUPED_COMMIT_WAIT_THRESHOLD |
12 | A usize | Threshold for deciding whether to wait for more transactions. If the current batch size is greater or equal to this threshold (and below ROCKSDB_GROUPED_COMMIT_MAX_BATCH_SIZE), then the coordinator will wait up to ROCKSDB_GROUPED_COMMIT_TIMEOUT to collect more transactions. Smaller batches are flushed immediately to preserve low latency. |
SURREAL_ROCKSDB_INITIAL_AUTO_READAHEAD_SIZE_(since v3.1.0)_ |
8,192 (8 KiB) | A usize | The size of the first prefetch. Each following read doubles it, up to SURREAL_ROCKSDB_MAX_AUTO_READAHEAD_SIZE. |
SURREAL_ROCKSDB_JOBS_COUNT |
Number of CPUs * 2 | A usize | The maximum number of threads to use for flushing and compaction. |
SURREAL_ROCKSDB_KEEP_LOG_FILE_NUM |
10 | A usize | The maximum number of information log files to keep. |
SURREAL_ROCKSDB_LEVEL0_SLOWDOWN_WRITES_TRIGGER_(since v3.1.0)_ |
8 | An i32 | The number of level-0 files at which RocksDB starts to slow down writes. The RocksDB default is 20. |
SURREAL_ROCKSDB_LEVEL0_STOP_WRITES_TRIGGER_(since v3.1.0)_ |
12 | An i32 | The number of level-0 files at which RocksDB stops writes until compaction reduces the count. Keep it above SURREAL_ROCKSDB_LEVEL0_SLOWDOWN_WRITES_TRIGGER. The RocksDB default is 36. |
SURREAL_ROCKSDB_MAX_AUTO_READAHEAD_SIZE_(since v3.1.0)_ |
262,144 (256 KiB) | A usize | The largest prefetch an iterator grows to. A larger value can make long range scans faster, but uses more memory for each iterator, so many concurrent scans multiply the cost. |
SURREAL_ROCKSDB_MAX_CONCURRENT_SUBCOMPACTIONS |
4 | A usize | The maximum number threads which will perform compactions. |
SURREAL_ROCKSDB_MAX_OPEN_FILES |
1024 | A usize | The maximum number of open files which can be opened by RocksDB. |
SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER |
2 (systems under 4 GiB), 4 (up to 16 GiB), 8 (up to 64 GiB), 32 (others) | A usize | The maximum number of write buffers which can be used. |
SURREAL_ROCKSDB_MEMTABLE_PREFIX_BLOOM_RATIO_(since v3.1.0)_ |
0.1 | An f64 | The size of the prefix bloom filter in each memtable, as a ratio of the write buffer size. RocksDB caps it at 0.25. Set to 0 to disable it. Only used when SURREAL_ROCKSDB_PREFIX_EXTRACTOR_ENABLED is true. |
SURREAL_ROCKSDB_MIN_BLOB_SIZE |
4096 | A usize | The minimum size in bytes of a value for it to be stored in blob files. |
SURREAL_ROCKSDB_MIN_WRITE_BUFFER_NUMBER_TO_MERGE |
2 | A usize | The minimum number of write buffers to merge before writing to disk. |
SURREAL_ROCKSDB_PERIODIC_COMPACTION_SECONDS_(since v3.1.0)_ |
3600 | A u64 | The interval in seconds after which RocksDB rewrites an SST file that no other compaction has touched. This removes old versions and tombstones from data that is rarely written. Set to 0 to disable. |
SURREAL_ROCKSDB_PREFIX_EXTRACTOR_ENABLED_(since v3.1.0)_ |
true | true, false | Whether SST bloom filters are built on table and key-type prefixes, so that a scan can skip SST files that hold nothing from the table it reads. |
SURREAL_ROCKSDB_RUNTIME_RESERVE_(since v3.1.0)_ |
2 | A usize | The number of runtime worker threads kept free for asynchronous work while other transactions wait on a storage call. A larger value keeps more threads free under load, but lowers the number of storage calls that can run at once. See SURREAL_RUNTIME_WORKER_THREADS. |
SURREAL_ROCKSDB_SCAN_VERIFY_CHECKSUMS_(since v3.1.0)_ |
true | true, false | Whether scans and counts verify the checksum of each block when it is first read from disk. Disabling it makes cold scans faster, and is only safe on trusted storage. |
SURREAL_ROCKSDB_SHUTDOWN_WAIT_FOR_COMPACT_SECONDS_(since v3.1.0)_ |
30 | A u64 | How long a graceful shutdown waits in seconds for a compaction that started after the final flush, so that the next start does not have to repeat it. Set to 0 to wait without a limit. |
SURREAL_ROCKSDB_SST_MAX_ALLOWED_SPACE_USAGE |
0 | A usize | The maximum allowed space usage for SST files in bytes. The default of 0 means unlimited and disables space monitoring. When this limit is reached, the datastore enters read-and-deletion-only mode, where only read and delete operations are allowed. This allows gradual space recovery through data deletion. |
SURREAL_ROCKSDB_STORAGE_LOG_LEVEL |
warn | none, full, error, warn, info, debug, trace | The information log level of the RocksDB library. |
SURREAL_ROCKSDB_TARGET_FILE_SIZE_BASE |
67,108,864 (64 MiB) | - | The target file size for compaction in bytes. |
SURREAL_ROCKSDB_TARGET_FILE_SIZE_MULTIPLIER |
2 | A usize | The target file size multiplier for each compaction level. |
SURREAL_ROCKSDB_THREAD_COUNT |
Number of CPUs on machine | A usize | The number of threads to start for flushing and compaction. |
SURREAL_ROCKSDB_UNIVERSAL_COMPRESSION_SIZE_PERCENT_(since v3.1.0)_ |
-1 | An i32 | The percentage of output files to compress. -1 compresses all of them. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_UNIVERSAL_MAX_MERGE_WIDTH_(since v3.1.0)_ |
4,294,967,295 (no limit) | A u32 | The largest number of files in a single merge. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_UNIVERSAL_MAX_SIZE_AMPLIFICATION_PERCENT_(since v3.1.0)_ |
200 | A u32 | The largest acceptable storage amplification, as a percentage of the size of the live data. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_UNIVERSAL_MIN_MERGE_WIDTH_(since v3.1.0)_ |
2 | A u32 | The smallest number of files in a single merge. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_UNIVERSAL_SIZE_RATIO_(since v3.1.0)_ |
1 | An i32 | How much larger, as a percentage, a file can be than the files before it and still be picked for the same merge. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_UNIVERSAL_STOP_STYLE_(since v3.1.0)_ |
total | similar_size, total | How RocksDB decides that a merge has collected enough files. Only used when SURREAL_ROCKSDB_COMPACTION_STYLE is universal. |
SURREAL_ROCKSDB_WAL_SIZE_LIMIT |
0 | A usize | The write-ahead-log size limit in MiB. |
SURREAL_ROCKSDB_WHOLE_KEY_FILTERING_(since v3.1.0)_ |
true | true, false | Whether SST bloom filters also hold whole keys as well as prefixes. Whole keys make point lookups faster, at the cost of larger filters. Disabling it can suit a workload that mostly scans. Only used when SURREAL_ROCKSDB_PREFIX_EXTRACTOR_ENABLED is true. |
SURREAL_ROCKSDB_WRITE_BUFFER_SIZE |
32 MiB (systems under 1 GiB), 64 MiB (up to 16 GiB), 128 MiB (others) | A usize | The amount of data each write buffer can build up in memory. |
SURREAL_SYNC_DATA |
true | true, false | Whether to sync writes to disk before acknowledgement. 2.x only: replaced in 3.0.0 by SURREAL_DATASTORE_SYNC_DATA. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY |
Dynamically calculated via greater of ((system memory / 2) - 1 GiB) and 16MiB | A usize | The maximum log file size in bytes. |
SURREAL_SURREALKV_BLOCK_SIZE |
65_536 (64 KiB) | A usize | The block size in bytes. |
SURREAL_SURREALKV_ENABLE_VLOG |
true | true, false | Whether to enable value log separation. |
SURREAL_SURREALKV_GROUPED_COMMIT_MAX_BATCH_SIZE |
4096 | A usize | The maximum number of transactions in a single grouped commit batch. This prevents unbounded memory growth while still allowing large batches for efficiency. Larger batches improve throughput but increase memory usage and commit latency. |
SURREAL_SURREALKV_GROUPED_COMMIT_TIMEOUT |
5ms | A duration in nanoseconds | The maximum wait time in nanoseconds before forcing a grouped commit. Ensures that transactions do not wait indefinitely under low concurrency and balances commit latency against write throughput. |
SURREAL_SURREALKV_GROUPED_COMMIT_WAIT_THRESHOLD |
12 | A usize | Threshold for deciding whether to wait for more transactions. If the current batch size is greater or equal to this threshold (and below SURREAL_SURREALKV_GROUPED_COMMIT_MAX_BATCH_SIZE), then the coordinator will wait up to SURREAL_SURREALKV_GROUPED_COMMIT_TIMEOUT to collect more transactions. Smaller batches are flushed immediately to preserve low latency. |
SURREAL_SURREALKV_MAX_MEMTABLE_SIZE_(since v3.1.0)_ |
Depends on system memory: 64 MiB below 1 GiB, 128 MiB below 4 GiB, 256 MiB below 16 GiB, 1 GiB below 64 GiB, and 4 GiB otherwise | A usize | The size of the memory area that holds the memtable. A transaction larger than this fails, so raise it for large transactions. |
SURREAL_SURREALKV_VERSIONED_INDEX |
false | true, false | Whether to enable versioned index. Only applies when versioning is enabled. |
SURREAL_SURREALKV_VLOG_MAX_FILE_SIZE |
64 MiB (systems under 4 GiB), 128 MiB (up to 16 GiB), 256 MiB (up to 64 GiB), 512 MiB (others) | A usize | The readahead buffer size used during compaction. |
SURREAL_SURREALKV_VLOG_THRESHOLD |
4096 (4 KiB) | A usize | The value log threshold in bytes. Values larger than this are stored in the value log. |
| Environment variable | Default | Allowed values | Notes |
|---|---|---|---|
SURREAL_TIKV_API_VERSION |
1 | A u8 | Which TiKV cluster API version to use. |
SURREAL_TIKV_ASYNC_COMMIT |
true | true, false | Whether to use asynchronous transactions. |
SURREAL_TIKV_KEYSPACE |
none | A string | A string specifying the keyspace identifier for data isolation. |
SURREAL_TIKV_GRPC_MAX_DECODING_MESSAGE_SIZE |
4,194,304 (4 MiB) | A usize | Sets the maximum decoding size of a gRPC message. |
SURREAL_TIKV_ONE_PHASE_COMMIT |
true | true, false | Whether to use one-phase transaction commit. |
SURREAL_TIKV_REQUEST_TIMEOUT |
10 | A usize | The duration in seconds for requests before they time out. |
SURREAL_TIKV_TLS_CA_PATH_(since v3.3.0)_ |
none | A file path | Path to the CA certificate used to verify the TiKV and PD servers. Setting all three SURREAL_TIKV_TLS_* variables switches the connection to mutual TLS (mTLS). |
SURREAL_TIKV_TLS_CERT_PATH_(since v3.3.0)_ |
none | A file path | Path to the client certificate that SurrealDB presents during mTLS. It must be set together with the CA and key paths. |
SURREAL_TIKV_TLS_KEY_PATH_(since v3.3.0)_ |
none | A file path | Path to the private key that matches the client certificate. It must be set together with the CA and certificate paths. If only some of the three paths are set, SurrealDB refuses to connect and reports which are missing. |
| Environment variable | Default value | Notes |
|---|---|---|
SURREAL_FOUNDATIONDB_TRANSACTION_MAX_RETRY_DELAY |
500 | The maximum delay between transaction retries in milliseconds. |
SURREAL_FOUNDATIONDB_TRANSACTION_RETRY_LIMIT |
5 | The maximum number of times a transaction can be retried. |
SURREAL_FOUNDATIONDB_TRANSACTION_TIMEOUT |
5000 | The maximum transaction timeout in milliseconds. |