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_BUILD_METADATA`	false	The version identifier of this build. Defaults to the CARGO_PKG_VERSION environment variable if not specified.
`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_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_FUNCTION_ALLOCATION_LIMIT`	20	Used to limit allocation for builtin functions.
`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_HTTP_MAX_ML_BODY_SIZE`	4398046511104 (4 GiB)	Maximum HTTP body size of the HTTP /ml endpoints
`SURREAL_HTTP_MAX_SQL_BODY_SIZE`	1048576 (1 MiB)	Maximum HTTP body size of the HTTP /sql endpoint
`SURREAL_HTTP_MAX_RPC_BODY_SIZE`	4194304 (4 MiB)	Maximum HTTP body size of the HTTP /rpc endpoint
`SURREAL_HTTP_MAX_KEY_BODY_SIZE`	16384 (16 KiB)	Maximum HTTP body size of the HTTP /key endpoints
`SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE`	1024 (1 KiB)	Maximum HTTP body size of the HTTP /signup endpoint.
`SURREAL_HTTP_MAX_SIGNIN_BODY_SIZE`	1024 (1 KiB)	The maximum HTTP body size of the HTTP /signin endpoints
`SURREAL_HTTP_MAX_IMPORT_BODY_SIZE`	4398046511104 (4 GiB)	Maximum HTTP body size of the HTTP /import endpoints
`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_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_SCRIPTING_MAX_MEMORY_LIMIT`	262144 (256 KiB)	Maximum stack size of the JavaScript function runtime.
`SURREAL_SCRIPTING_MAX_STACK_SIZE`	2097152 (2 MiB)	Maximum memory limit of the JavaScript function runtime.
`SURREAL_SURREALCS_CONNECTION_POOL_SIZE`	Number of CPUs on the current device	Size of the SurrealCS connection pool.
`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`	24	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.

This allows the connection pool size to be determined by an environment variable, falling back to the number of CPUs on the device if no environment variable has been specified. The new environment variable is:

Command environment variables

Many of the arguments passed into the CLI can be set using these 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

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_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_KEY`	surreal start	kvs-key	Path to the private key 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_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.

Storage backend environment variables

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

FoundationDB

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 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_KEEP_LOG_FILE_NUM`	20

Edit this page on GitHub

Version command Reference Guides