Environment variables

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

Environment variables are divided into four types:

SurrealDB environment variables: environment variables that pertain to the overall running of a SurrealDB server. Example: SURREAL_DEFAULT_DATABASE.
Command environment variables: environment variables that can be used in lieu of a command flag. Example: SURREAL_STRICT=true surreal start, equivalent to surreal start --strict.
Storage backend environment variables: environment variables that pertain to a certain storage backend. Example: SURREAL_SURREALKV_MAX_SEGMENT_SIZE.
SurrealDB Cloud environment variables: environment variables that are set via the Configure instance sidebar for a SurrealDB Cloud instance.

SurrealDB environment variables

Environment variable	Default	Allowed values	Notes
`SURREAL_BUCKET_FOLDER_ALLOWLIST`	none	Comma-separated paths	Specifies a list of paths in which files can be accessed.
`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_CHANGEFEED_GC_INTERVAL`	30s	A duration	The interval at which to perform changefeed garbage collection.
`SURREAL_COUNT_BATCH_SIZE` Available since: v2.2.0	10,000	A usize	The maximum number of keys that should be scanned at once for count queries.
`SURREAL_DATASTORE_CACHE_SIZE` Available since: v2.1.0	1,000	A usize	The number of definitions which can be cached across transactions.
`SURREAL_DEFAULT_DATABASE` Available since: v3.0.0-beta	main	A string	The default database to use when starting a SurrealDB instance.
`SURREAL_DEFAULT_NAMESPACE` Available since: v3.0.0-beta	main	A string	The default namespace to use when starting a SurrealDB instance.
`SURREAL_ASYNC_EVENT_PROCESSING_INTERVAL` Available since: v3.0.0-beta	5s	A duration	The interval at which to process async events.
`SURREAL_EXPORT_BATCH_SIZE`	1000	A usize	The maximum number of keys that should be scanned at once for export queries.
`SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT`	50000	A usize	The number of result records which will trigger on-disk sorting.
`SURREAL_FILE_ALLOWLIST` Available since: v2.1.5	none	Comma-separated paths	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_GLOBAL_BUCKET`	none	A string	Specifies the name of a global bucket for file data.
`SURREAL_GENERATION_ALLOCATION_LIMIT`	20	An integer	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²⁰).
`SURREAL_GLOBAL_BUCKET_ENFORCED`	false	true, false	Whether to enforce a global bucket for file data.
`SURREAL_HNSW_CACHE_SIZE`	268,435,456 (256 MiB)	A usize	The maximum size of the HNSW vector cache.
`SURREAL_HTTP_CONNECT_TIMEOUT_SECS`	30	A usize	The timeout for connecting to HTTP endpoints.
`SURREAL_HTTP_IDLE_TIMEOUT_SECS`	90	A usize	The timeout for idle HTTP connections before closing.
`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_IMPORT_BODY_SIZE`	4,398,046,511,104 (4 GiB)	A usize	Maximum HTTP body size of the HTTP /import endpoints
`SURREAL_HTTP_MAX_KEY_BODY_SIZE`	16,384 (16 KiB)	A usize	Maximum HTTP body size of the HTTP /key endpoints
`SURREAL_HTTP_MAX_ML_BODY_SIZE`	4,398,046,511,104 (4 GiB)	A usize	Maximum HTTP body size of the HTTP /ml endpoints
`SURREAL_HTTP_MAX_RPC_BODY_SIZE`	4,194,304 (4 MiB)	A usize	Maximum HTTP body size of the HTTP /rpc endpoint.
`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_SIGNIN_BODY_SIZE`	1024 (1 KiB)	A usize	The maximum HTTP body size of the HTTP /signin endpoints
`SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE`	1024 (1 KiB)	A usize	Maximum HTTP body size of the HTTP /signup endpoint.
`SURREAL_IDIOM_RECURSION_LIMIT`	256	A usize	The maximum recursive idiom path depth allowed.
`SURREAL_IMPORT_FILE`	none	A file path	Path to a SurrealQL file that will be imported when starting the server.
`SURREAL_INDEXING_BATCH_SIZE`	250	A usize	The maximum number of keys to scan at once per concurrent indexing batch.
`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.
`SURREAL_MAX_BATCH_SIZE`	5,000	A usize	The maximum batch size for Scanner adaptive fetching.
`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_HTTP_IDLE_CONNECTIONS`	1000	A usize	The maximum number of idle HTTP connections to maintain.
`SURREAL_MAX_HTTP_IDLE_CONNECTIONS_PER_HOST`	128	A usize	The maximum number of idle HTTP connections to maintain per host.
`SURREAL_MAX_HTTP_REDIRECTS` Available since: v2.0.5	10	A usize	The maximum number of HTTP redirects allowed within http functions.
`SURREAL_MAX_OBJECT_PARSING_DEPTH`	100	A usize	Specifies how deep the parser will parse nested objects and arrays in a query.
`SURREAL_MAX_ORDER_LIMIT_PRIORITY_QUEUE_SIZE` Available 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	Specifies how deep the parser will parse recursive queries (queries within queries).
`SURREAL_MEMORY_THRESHOLD` Available since: v2.1.5	0	A usize or suffixed integer	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	A usize	How many concurrent network requests can be handled at once
`SURREAL_NO_DEFAULTS` Available since: v3.0.0-beta	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_NODE_MEMBERSHIP_CHECK_INTERVAL`	15s	A duration	The interval at which to process and archive inactive nodes.
`SURREAL_NODE_MEMBERSHIP_CLEANUP_INTERVAL`	300s	A duration	The interval at which to process and cleanup archived nodes.
`SURREAL_NODE_MEMBERSHIP_REFRESH_INTERVAL`	3s	A duration	The interval at which to refresh node registration information.
`SURREAL_NORMAL_FETCH_SIZE`	500	A duration	The maximum number of keys that should be scanned at once in general queries.
`SURREAL_REGEX_CACHE_SIZE`	1000	A duration	The number of computed regexes which can be cached in the engine.
`SURREAL_REGEX_SIZE_LIMIT` Available since: v2.1.5	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_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.
`SURREAL_SCRIPTING_MAX_MEMORY_LIMIT`	2,097,152 (2 MiB)	A usize	Maximum memory limit of the JavaScript function runtime.
`SURREAL_SCRIPTING_MAX_STACK_SIZE`	262_144 (256 KiB)	A usize	Maximum stack size of the JavaScript function runtime.
`SURREAL_SCRIPTING_MAX_TIME_LIMIT` Available since: v2.0.5	5000 (5000 milliseconds or 5 seconds	A usize)	Maximum allowed time in milliseconds that a JavaScript function is allowed to run for.
`SURREAL_SURREALISM_CACHE_SIZE` Available since: v3.0.0-beta	100	A usize	The number of surrealism modules which can be cached across transactions.
`SURREAL_TELEMETRY_DISABLE_METRICS` Available since: v2.1.3	false	true, false	Whether to disable sending metrics to the GRPC OTEL collector.
`SURREAL_TELEMETRY_DISABLE_TRACING` Available since: v2.1.3	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_TEMPORARY_DIRECTORY`	none	A string to a directory	Sets the directory for storing temporary database files.
`SURREAL_TOKIO_CONSOLE_ENABLED` Available since: v3.0.0-beta	false	true, false	Whether to enable tokio console.
`SURREAL_TOKIO_CONSOLE_RETENTION` Available since: v3.0.0-beta	60	A usize	How long, in seconds, to retain data for completed events.
`SURREAL_TOKIO_CONSOLE_SOCKET_ADDR` Available since: v3.0.0-beta	false	A string to a socket address	The socket address that Tokio Console will bind to.
`SURREAL_TRANSACTION_CACHE_SIZE`	10,000	A usize	Specifies the number of items which can be cached within a single transaction.
`SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE`	134,217,728 (128 MiB)	A usize	Maximum WebSocket message size.
`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.
`SURREAL_WEBSOCKET_RESPONSE_FLUSH_PERIOD`	3	A usize	How often (in milliseconds) any buffered responses are flushed to the WebSocket client.

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 or a required argument 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

Boolean values in command environment variables

A command environment variable that takes a boolean will be set to true if the flag is present, and following it with true will cause an error.

For example, the SURREAL_CAPS_ALLOW_ALL environment variable is used to set whether to allow all capabilities such as scripting and allowing network access. The flag --allow-all is all that is needed to set to true. But as an environment variable, the value true must be included to override its default false value.

SURREAL_CAPS_ALLOW_ALL example
# set to default false
surreal start

# Same, but implicitly shown
SURREAL_CAPS_ALLOW_ALL=false surreal start

# Set to true
SURREAL_CAPS_ALLOW_ALL=true surreal start

# Set to true
surreal start --allow-all

# Error: only --allow-all needed to set to true
surreal start --allow-all true

Environment variable	Command arg	For command(s)	Default	Allowed values	Details
`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	A string to an address	The hostname or IP address(es) to listen for 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_EXPERIMENTAL`	`allow-experimental`	`start`	none	graphql, define_api, files, surrealism (comma-separated)	Allow execution of experimental features.
`SURREAL_CAPS_ALLOW_FUNC`	`allow-funcs`	`start`	false	true, false, comma-separated strings to function paths	Allow execution of all functions except for functions that are specifically denied.
`SURREAL_CAPS_ALLOW_GUESTS`	`allow-guests`	`start`	true	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`	true	true, false	Allow execution of embedded scripting functions.
`SURREAL_CAPS_ALLOW_INSECURE_STORABLE_CLOSURES` Available since: v2.5.0	`allow-insecure-storable-closures`	`start`	false	true, false	Takes a boolean. Prevents closures from being stored, which eliminates a potential attack surface. For version 2.5.0, this can still be allowed by using this capability.
`SURREAL_CAPS_DENY_ALL`	`deny-all`	`start`	false	true, false	Deny all capabilities.
`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_CLIENT_IP`	`client-ip`	`start`	none	none, socket, CF-Connecting-IP, Fly-Client-IP, True-Client-IP, X-Real-IP, X-Forwarded-For	The method of detecting the client’s IP address.
`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_HIDE_WELCOME`	`hide-welcome`	`sql`	false	true, false	Whether to show the welcome message when starting the REPL.
`SURREAL_INDEX_COMPACTION_INTERVAL` Available since: v3.0.0-beta	`index-compaction-interval`	`start`	5s	A duration	The interval at which to perform changefeed garbage collection.
`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	A string to a path	Path to the CA file used when connecting to the remote KV store.
`SURREAL_KVS_CRT`	`kvs-crt`	`start`	none	A string to a path	Path to the certificate file used when connecting to the remote KV store.
`SURREAL_KVS_KEY`	`kvs-key`	`start`	none	A string to a path	Path to the private key file used when connecting to the remote KV store.
`SURREAL_LOG`	`log`	`start`, `fix`	info	none, full, error, warn, info, debug, trace	The logging level for the database server.
`SURREAL_LOG_FILE_ENABLED` Available since: v2.4.0	`log-file-enabled`	`start`	true	true, false	Toggles file output (default: false)
`SURREAL_LOG_FILE_FORMAT` Available since: v2.4.0	`log-file-format`	`start`	none	text, json	The format for log file output.
`SURREAL_LOG_FILE_LEVEL` Available 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` Available since: v2.4.0	`log-file-name`	`start`	surrealdb.log	String to a file	Filename for logs (default: `surrealdb.log`)
`SURREAL_LOG_FILE_PATH` Available since: v2.4.0	`log-file-path`	`start`	logs	String to a path	Sets the directory for logs
`SURREAL_LOG_FILE_ROTATION` Available since: v2.4.0	`log-file-rotation`	`start`	daily	daily, hourly, never	Sets the rotation duration for logs.
`SURREAL_LOG_FORMAT` Available since: v2.4.0	`log-format`	`start`	text	text, json	Sets the format for logs.
`SURREAL_LOG_OTEL_LEVEL` `log-otel-level` Available since: v2.4.0	`start`	SURREAL_LOG logging level	none, full, error, warn, info, debug, trace	Override the logging level for OpenTelemetry
`SURREAL_LOG_SOCKET` Available since: v3.0.0-beta	`log-socket`	`start`	none	String to a host:port	Send logs to the specified host:port
`SURREAL_LOG_SOCKET_FORMAT` Available since: v3.0.0-beta	`log-socket-format`	`start`	text	text, json	Set the format of the logs to the socket.
`SURREAL_LOG_SOCKET_LEVEL` Available since: v3.0.0-beta	`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_IDENTIFICATION_HEADERS`	`no-identification-headers`	`start`	false	true, false	Whether to suppress the server name and version headers.
`SURREAL_PASS`	`pass`	`export`, `import`, `sql`, `start`	none	A string	Database authentication password to use when connecting.
`SURREAL_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_QUERY_TIMEOUT`	`query-timeout`	`start`	none	A duration	The maximum duration that a set of statements can run for.
`SURREAL_SLOW_QUERY_LOG_THRESHOLD` `slow-log-threshold` Available since: v2.3.8	`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_ALLOW` `slow-log-param-allow` Available since: v2.3.9	`start`	none	Comma-separated strings	A comma-separated list of parameter names to include in slow query logs.
`SURREAL_SLOW_QUERY_LOG_PARAM_DENY` Available 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.
`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.