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	The maximum number of keys that should be scanned at once for count queries.
`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	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_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_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_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_IMPORT_FILE`	None	Path to a SurrealQL file that will be imported when starting the server.
`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_CONCURRENT_TASKS`	64	Specifies how many concurrent jobs can be buffered in the worker channel.
`SURREAL_MAX_OBJECT_PARSING_DEPTH`	10	Specifies how deep the parser will parse nested objects and arrays in a query.
`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`		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_REGEX_SIZE_LIMIT`	10,485,760	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_NORMAL_FETCH_SIZE`	50	The maximum number of keys that should be scanned at once in general queries.
`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_TIME_LIMIT`	5000 (5000 milliseconds or 5 seconds)	Maximum allowed time that a JavaScript function is allowed to run for.
`SURREAL_SCRIPTING_MAX_STACK_SIZE`	262144 (256 KiB)	Maximum stack size of the JavaScript function runtime.
`SURREAL_SURREALCS_CONNECTION_POOL_SIZE`	Number of CPUs on the current device	Size of the SurrealCS connection pool.
`SURREAL_TELEMETRY_DISABLE_METRICS`	false	Disables sending metrics to the GRPC OTEL collector. Available since SurrealDB v2.1.3
`SURREAL_TELEMETRY_DISABLE_TRACING`	false	Disables sending traces to the GRPC OTEL collector. Available since SurrealDB v2.1.3
`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`	100	Configuring the WebSocket buffer size and the WebSocket response queue size.
`SURREAL_WEBSOCKET_RESPONSE_CHANNEL_SIZE`	100	Configuring the WebSocket buffer size and the WebSocket response queue size.

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
`SURREAL_FOUNDATIONDB_TRANSACTION_TIMEOUT`	5000
`SURREAL_FOUNDATIONDB_TRANSACTION_RETRY_LIMIT`	5

RocksDB environment variables

Environment variable	Default value	Notes
`SURREAL_ROCKSDB_THREAD_COUNT`	Number of CPUs on machine
`SURREAL_ROCKSDB_WRITE_BUFFER_SIZE`	268435456 (256 MiB)
`SURREAL_ROCKSDB_TARGET_FILE_SIZE_BASE`	536870912 (512 MiB)
`SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER`	32
`SURREAL_ROCKSDB_MIN_WRITE_BUFFER_NUMBER_TO_MERGE`	4
`SURREAL_ROCKSDB_ENABLE_PIPELINED_WRITES`	true
`SURREAL_ROCKSDB_ENABLE_BLOB_FILES`	true
`SURREAL_ROCKSDB_MIN_BLOB_SIZE`	4096
`SURREAL_ROCKSDB_BLOCK_CACHE_SIZE`	Whichever is larger of “System total memory / 2 - 1GiB” and “512MiB”	RocksDB block cache size in bytes
`SURREAL_ROCKSDB_KEEP_LOG_FILE_NUM`	20
`SURREAL_ROCKSDB_SYNC_DATA`	false
`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_SYNC_DATA`	false
`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.

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