Environment variables

Environment variables can be used to tailor the behaviour of a running SurrealDB instance.

SurrealDB environment variables

Environment variable	Default value	Notes
`SURREAL_BUCKET_FOLDER_ALLOWLIST`	empty	Specifies a list of paths in which files can be accessed.
`SURREAL_BUILD_METADATA`	false	The version identifier of this build. Defaults to the CARGO_PKG_VERSION environment variable if not specified.
`SURREAL_COUNT_BATCH_SIZE`	10,000	Available since: v2.2.0 The maximum number of keys that should be scanned at once for count queries.
`SURREAL_DATASTORE_CACHE_SIZE`	1,000	Available since: v2.1.0 The number of definitions which can be cached across transactions.
`SURREAL_EXPERIMENTAL_BEARER_ACCESS`	false	Enable experimental bearer access and stateful access grant management. Still under active development. Using this experimental feature may introduce risks related to breaking changes and security issues.
`SURREAL_EXPERIMENTAL_GRAPHQL`	false	Enables experimental graphql integration. Still under active development. Using this experimental feature may introduce risks related to breaking changes and security issues.
`SURREAL_EXPORT_BATCH_SIZE`	1000	The maximum number of keys that should be scanned at once for export queries.
`SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT`	50000	Specifies the buffer limit for external sorting.
`SURREAL_FILE_ALLOWLIST`	20	Available since: v2.1.5 Limits file access for the mapper filter to only the specified allowed file paths. The paths must be provided as absolute paths, separated by a colon (:) on Unix-like systems or a semicolon (;) on Windows.
`SURREAL_FUNCTION_ALLOCATION_LIMIT`	20	Used to limit allocation for builtin functions.
`SURREAL_GLOBAL_BUCKET`	None	Specifies the name of a global bucket for file data.
`SURREAL_GENERATION_ALLOCATION_LIMIT`	20	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 2^20).
`SURREAL_GLOBAL_BUCKET_ENFORCED`	false	Whether to enforce a global bucket for file data.
`SURREAL_HTTP_MAX_API_BODY_SIZE`	1 MiB	The maximum HTTP body size of the HTTP /api endpoint.
`SURREAL_HTTP_MAX_IMPORT_BODY_SIZE`	4398046511104 (4 GiB)	Maximum HTTP body size of the HTTP /import endpoints
`SURREAL_HTTP_MAX_KEY_BODY_SIZE`	16384 (16 KiB)	Maximum HTTP body size of the HTTP /key endpoints
`SURREAL_HTTP_MAX_ML_BODY_SIZE`	4398046511104 (4 GiB)	Maximum HTTP body size of the HTTP /ml endpoints
`SURREAL_HTTP_MAX_RPC_BODY_SIZE`	4194304 (4 MiB)	Maximum HTTP body size of the HTTP /rpc endpoint.
`SURREAL_HTTP_MAX_SQL_BODY_SIZE`	1048576 (1 MiB)	Maximum HTTP body size of the HTTP /sql endpoint
`SURREAL_HTTP_MAX_SIGNIN_BODY_SIZE`	1024 (1 KiB)	The maximum HTTP body size of the HTTP /signin endpoints
`SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE`	1024 (1 KiB)	Maximum HTTP body size of the HTTP /signup endpoint.
`SURREAL_IDIOM_RECURSION_LIMIT`	256	The maximum recursive idiom path depth allowed.
`SURREAL_IMPORT_FILE`	None	Path to a SurrealQL file that will be imported when starting the server.
`SURREAL_INDEXING_BATCH_SIZE`	250	The maximum number of keys to scan at once per concurrent indexing batch.
`SURREAL_INSECURE_FORWARD_ACCESS_ERRORS`	false	Forward all signup/signin/authenticate query errors to a client performing authentication. Do not use in production.
`SURREAL_MAX_COMPUTATION_DEPTH`	120	/// Specifies how deep recursive computation will go before erroring.
`SURREAL_MAX_CONCURRENT_TASKS`	64	Specifies how many concurrent jobs can be buffered in the worker channel.
`SURREAL_MAX_HTTP_REDIRECTS`	10	Available since: v2.0.5 The maximum number of HTTP redirects allowed within http functions.
`SURREAL_MAX_OBJECT_PARSING_DEPTH`	10	Specifies how deep the parser will parse nested objects and arrays in a query.
`SURREAL_MAX_ORDER_LIMIT_PRIORITY_QUEUE_SIZE`	1000	Available since: v2.2.0 The maximum size of the priority queue triggering usage of the priority queue for the result collector.
`SURREAL_MAX_QUERY_PARSING_DEPTH`	20	Specifies how deep the parser will parse recursive queries (queries within queries).
`SURREAL_MAX_STREAM_BATCH_SIZE`	1000	The maximum number of keys that should be fetched when streaming range scans in a Scanner.
`SURREAL_MEMORY_THRESHOLD`		Available since: v2.1.5 Configuring the memory threshold which can be used across the programme to check if the amount of memory available to the programme is lower than required. 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). If the environment variable is not specified, then the threshold is not used, and no memory limit is enabled.
`SURREAL_NET_MAX_CONCURRENT_REQUESTS`	1,048,576 concurrent requests	Adds a global limit for concurrent server requests, and introduces a new environment variable
`SURREAL_NORMAL_FETCH_SIZE`	500	The maximum number of keys that should be scanned at once in general queries.
`SURREAL_REGEX_CACHE_SIZE`	100	The number of computed regexes which can be cached in the engine.
`SURREAL_REGEX_SIZE_LIMIT`	10,485,760	Available since: v2.1.5 Limits the maximum allowed size (in bytes) for compiled regular expressions. This prevents excessive memory consumption when building complex or very large regex patterns.
`SURREAL_RUNTIME_MAX_BLOCKING_THREADS`	512	Number of threads which can be started for blocking operations.
`SURREAL_RUNTIME_STACK_SIZE`	10485760 (10 MiB)	Runtime thread memory stack size. Stack size is doubled if compiled from source in Debug mode.
`SURREAL_RUNTIME_WORKER_THREADS`	Number of CPU cores (minimum 4)	Number of runtime worker threads used to start.
`SURREAL_SCRIPTING_MAX_MEMORY_LIMIT`	2097152 (2 MiB)	Maximum memory limit of the JavaScript function runtime.
`SURREAL_SCRIPTING_MAX_STACK_SIZE`	262144 (256 KiB)	Maximum stack size of the JavaScript function runtime.
`SURREAL_SCRIPTING_MAX_TIME_LIMIT`	5000 (5000 milliseconds or 5 seconds)	Available since: v2.0.5 Maximum allowed time that a JavaScript function is allowed to run for.
`SURREAL_SURREALCS_CONNECTION_POOL_SIZE`	Number of CPUs on the current device	Available since: v2.0.2 Size of the SurrealCS connection pool.
`SURREAL_TELEMETRY_DISABLE_METRICS`	false	Available since: v2.1.3 Disables sending metrics to the GRPC OTEL collector.
`SURREAL_TELEMETRY_DISABLE_TRACING`	false	Available since: v2.1.3 Disables sending traces to the GRPC OTEL collector.
`SURREAL_TELEMETRY_NAMESPACE`	None	If set then use this as value for the namespace label when sending telemetry
`SURREAL_TELEMETRY_PROVIDER`	None	If set to “otlp” then telemetry is sent to the GRPC OTEL collector.
`SURREAL_TEMPORARY_DIRECTORY`	None	Sets the directory for storing temporary database files.
`SURREAL_TRANSACTION_CACHE_SIZE`	10000	Specifies the number of items which can be cached within a single transaction.
`SURREAL_WEBSOCKET_MAX_CONCURRENT_REQUESTS`	4 times the number of CPU cores, minimum 12	Maximum concurrent tasks that can be handled on each WebSocket.
`SURREAL_WEBSOCKET_MAX_FRAME_SIZE`	16777216 (16 MiB)	Maximum WebSocket frame size.
`SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE`	134217728 (128 MiB)	Maximum WebSocket message size.
`SURREAL_WEBSOCKET_RESPONSE_BUFFER_SIZE`	0	How many responses can be buffered when delivering to the client.
`SURREAL_WEBSOCKET_RESPONSE_CHANNEL_SIZE`	100	Configuring the WebSocket buffer size and the WebSocket response queue size.
`SURREAL_WEBSOCKET_RESPONSE_FLUSH_PERIOD`	3	How often (in milliseconds) any buffered responses are flushed to the WebSocket client.

Environment variable	For command(s)	Command arg	Details
`SURREAL_AUTH_LEVEL`	surreal export, import, sql	auth-level	Authentication level to use when connecting.
`SURREAL_BIND`	surreal start	bind	The hostname or IP address(es) to listen for connections on.
`SURREAL_CAPS_ALLOW_ALL`	surreal start	allow-all	Allow all capabilities.
`SURREAL_CAPS_ALLOW_ARBITRARY_QUERY`	surreal start	allow-arbitrary-query	Allows arbitrary queries to be used by user groups. Possible user groups are: ‘guest’, ‘record’, and ‘system’.
`SURREAL_CAPS_ALLOW_EXPERIMENTAL`	surreal start	allow-experimental	Allow execution of experimental features.
`SURREAL_CAPS_ALLOW_FUNC`	surreal start	allow-funcs	Allow execution of all or certain functions.
`SURREAL_CAPS_ALLOW_GUESTS`	surreal start	allow-guests	Allow guest users to execute queries.
`SURREAL_CAPS_ALLOW_NET`	surreal start	allow-net	Allow all or certain outbound network access.
`SURREAL_CAPS_ALLOW_SCRIPT`	surreal start	allow-scripting	Allow execution of embedded scripting functions.
`SURREAL_CAPS_DENY_ALL`	surreal start	deny-all	Deny all capabilities.
`SURREAL_CAPS_DENY_FUNC`	surreal start	deny-funcs	Deny execution of all or certain functions.
`SURREAL_CAPS_DENY_GUESTS`	surreal start	deny-guests	Deny guest users to execute queries.
`SURREAL_CAPS_DENY_NET`	surreal start	deny-net	Deny all or certain outbound access paths.
`SURREAL_CAPS_DENY_SCRIPT`	surreal start	deny-scripting	Deny execution of embedded scripting functions.
`SURREAL_CLIENT_IP`	surreal start	client-ip	The method of detecting the client’s IP address.
`SURREAL_DATABASE`	surreal export, import, sql	database	The database selected for the operation.
`SURREAL_HIDE_WELCOME`	surreal sql	hide-welcome	Whether to show welcome message.
`SURREAL_KEY`	surreal start	key	Encryption key to use for on-disk encryption.
`SURREAL_KVS_CA`	surreal start	kvs-ca	Path to the CA file used when connecting to the remote KV store.
`SURREAL_KVS_CERT`	surreal start	kvs-cert	Path to the certificate file used when connecting to the remote KV store.
`SURREAL_KVS_KEY`	surreal start	kvs-key	Path to the private key file used when connecting to the remote KV store.
`SURREAL_LOG`	surreal fix, start	log	The logging level for the database server.
`SURREAL_NAME`	surreal ml export	name	The name of the model.
`SURREAL_NAMESPACE`	surreal export, import, sql	namespace	The namespace selected for the operation.
`SURREAL_NO_BANNER`	surreal start	no-banner	Whether to hide the startup banner.
`SURREAL_NO_IDENTIFICATION_HEADERS`	surreal start	no-identification-headers	Whether to suppress the server name and version headers.
`SURREAL_PASS`	surreal export, import, sql, start	password, pass	Database authentication password to use when connecting.
`SURREAL_PATH`	surreal fix, start	path	Database path used for storing data.
`SURREAL_QUERY_TIMEOUT`	surreal start	query-timeout	The maximum duration that a set of statements can run for.
`SURREAL_STRICT`	start	strict	Whether strict mode is enabled on this database instance.
`SURREAL_TEMPORARY_DIRECTORY`	surreal start	temporary-directory	Sets the directory for storing temporary database files
`SURREAL_TICK_INTERVAL`	surreal start	tick-interval	The interval at which to run node agent tick (including garbage collection).
`SURREAL_TOKEN`	surreal export, import, sql	token	Authentication token in JWT format to use when connecting.
`SURREAL_TRANSACTION_TIMEOUT`	surreal start	transaction-timeout	The maximum duration that any single transaction can run for.
`SURREAL_UNAUTHENTICATED`	surreal start	unauthenticated	Whether to allow unauthenticated access.
`SURREAL_USER`	surreal export, import, sql, start	username, user	Database authentication username to use when connecting.
`SURREAL_VERSION`	surreal ml export	name	The version of the model.
`SURREAL_WEB_CRT`	surreal start	web-crt	Path to the certificate file for encrypted client connections.
`SURREAL_WEB_KEY`	surreal start	web-key	Path to the private key file for encrypted client connections.

Environment variables by storage backend

These environment variables are used to configure the storage backend for SurrealDB.

FoundationDB environment variables

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.

RocksDB environment variables

Environment variable	Default value	Notes
`SURREAL_ROCKSDB_BACKGROUND_FLUSH`	false	Whether to enable background WAL file flushing.
`SURREAL_ROCKSDB_BACKGROUND_FLUSH_INTERVAL`	200	The interval in milliseconds between background flushes.
`SURREAL_ROCKSDB_BLOCK_CACHE_SIZE`	Whichever is larger of “System total memory / 2 - 1GiB” and “512MiB”	RocksDB block cache size in bytes
`SURREAL_ROCKSDB_BLOCK_SIZE`	64 KiB	The size of each uncompressed data block in bytes.
`SURREAL_ROCKSDB_COMPACTION_READAHEAD_SIZE`	16 MiB	The readahead buffer size used during compaction.
`SURREAL_ROCKSDB_COMPACTION_STYLE`	”level”	Available since: v2.0.3 Use to specify the database compaction style.
`SURREAL_ROCKSDB_DELETION_FACTORY_DELETION_COUNT`	50	Available since: v2.0.3 The number of deletions to track in the window.
`SURREAL_ROCKSDB_DELETION_FACTORY_RATIO`	0.5	Available since: v2.0.3 The ratio of deletions to track in the window.
`SURREAL_ROCKSDB_DELETION_FACTORY_WINDOW_SIZE`	1000	Available since: v2.0.3 The size of the window used to track deletions.
`SURREAL_ROCKSDB_ENABLE_BLOB_FILES`	true	Whether to enable separate key and value file storage.
`SURREAL_ROCKSDB_ENABLE_MEMORY_MAPPED_READS`	false	Whether to enable memory-mapped reads.
`SURREAL_ROCKSDB_ENABLE_MEMORY_MAPPED_WRITES`	false	Whether to enable memory-mapped writes.
`SURREAL_ROCKSDB_ENABLE_PIPELINED_WRITES`	true	Whether to use separate queues for WAL writes and memtable writes.
`SURREAL_ROCKSDB_FILE_COMPACTION_TRIGGER`	16	The number of files needed to trigger level 0 compaction.
`SURREAL_ROCKSDB_JOBS_COUNT`	Number of CPUs * 2	Available since: v2.0.3 The maximum number of threads to use for flushing and compaction.
`SURREAL_ROCKSDB_KEEP_LOG_FILE_NUM`	20	The maximum number of information log files to keep.
`SURREAL_ROCKSDB_MAX_CONCURRENT_SUBCOMPACTIONS`	4	The maximum number threads which will perform compactions.
`SURREAL_ROCKSDB_MAX_OPEN_FILES`	1024	The maximum number of open files which can be opened by RocksDB.
`SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER`	32	The maximum number of write buffers which can be used.
`SURREAL_ROCKSDB_MIN_BLOB_SIZE`	4096	The minimum size of a value for it to be stored in blob files.
`SURREAL_ROCKSDB_MIN_WRITE_BUFFER_NUMBER_TO_MERGE`	6	The minimum number of write buffers to merge before writing to disk.
`SURREAL_ROCKSDB_STORAGE_LOG_LEVEL`	”warn”	The information log level of the RocksDB library.
`SURREAL_ROCKSDB_TARGET_FILE_SIZE_BASE`	128 MiB	The target file size for compaction in bytes.
`SURREAL_ROCKSDB_TARGET_FILE_SIZE_MULTIPLIER`	10	The target file size multiplier for each compaction level.
`SURREAL_ROCKSDB_THREAD_COUNT`	Number of CPUs on machine	The number of threads to start for flushing and compaction.
`SURREAL_ROCKSDB_WAL_SIZE_LIMIT`	1024 MB (1 GB)	The write-ahead-log size limit in MiB.
`SURREAL_ROCKSDB_WRITE_BUFFER_SIZE`	268435456 (256 MiB)	The amount of data each write buffer can build up in memory.
`SURREAL_SYNC_DATA`	false	Controls the behaviour of RocksDB and SurrealKV. Allows data durability configuration, ensuring that the database can be configured for writes to be synced to disk before transactions are confirmed to be completed.

SurrealKV environment variables

Environment variable	Default value	Notes
`SURREAL_SURREALKV_MAX_SEGMENT_SIZE`	512 MiB	The maximum size of a single data file segment.
`SURREAL_SURREALKV_MAX_VALUE_CACHE_SIZE`	Whichever is larger of “System total memory / 2 - 1GiB” and “512MiB”	The size of the in-memory value cache for SurrealKV.
`SURREAL_SURREALKV_MAX_VALUE_THRESHOLD`	64	The size in bytes to store values in the tree, or a separate log file.
`SURREAL_SYNC_DATA`	false	Controls the behaviour of RocksDB and SurrealKV. Allows data durability configuration, ensuring that the database can be configured for writes to be synced to disk before transactions are confirmed to be completed.

TiKV environment variables

Environment variable	Default value	Notes
`SURREAL_TIKV_API_VERSION`	1	Which TiKV cluster API version to use.
`SURREAL_TIKV_ASYNC_COMMIT`	true	Whether to use asynchronous transactions.
`SURREAL_TIKV_KEYSPACE`	None	A string specifying the keyspace identifier for data isolation.
`SURREAL_TIKV_ONE_PHASE_COMMIT`	true	Whether to use one-phase transaction commit.
`SURREAL_TIKV_REQUEST_TIMEOUT`	10	The duration in seconds for requests before they time out.

Command environment variables

Many of the arguments passed into the CLI can be set using the above environment variables instead.

As each of these environment variables correspond to a flag passed into a command, it is good practice to put together a command that matches the environment variables you wish to set. Once the database server conforms to your expected behaviour, you can then pull out the values passed into each flag for your environment variables.

For example, take the following command to start the database.

surreal start --user root --pass root --allow-net --deny-funcs "crypto::md5, http::post, http::delete"

If we now wanted to use environment variables instead of the --allow-net and --deny-funcs flags, we would use the SURREAL_CAPS_ALLOW_NET and SURREAL_CAPS_DENY_FUNC environment variables.

As the --allow-net flag was passed in without a following value, the same will be the case with the SURREAL_CAPS_ALLOW_NET environment variable, becoming SURREAL_CAPS_ALLOW_NET=. The --deny-funcs flag can also be used on its own to deny execution of all functions, but in this case is followed by a string to indicate which exact functions are not allowed to be executed. As such, the SURREAL_CAPS_DENY_FUNC environment variable must also be followed by a string, becoming SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete".

The command would then look like the following:

Bash
PowerShell

SURREAL_CAPS_ALLOW_NET
SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
surreal start --user root --pass root

$env:SURREAL_CAPS_ALLOW_NET
$env:SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
surreal start --user root --pass root

Surreal Cloud environment variables

Instances on Surreal Cloud are not started with a CLI command or environment variables. Instead, they can be set on the Configure Instance panel.

Edit this page on GitHub

Version command Reference Guides

SurrealDB