SurrealDB Docs Logo

Enter a search query

Environment variables

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

SurrealDB environment variables

Environment variableDefault valueNotes
SURREAL_BUILD_METADATAfalseThe version identifier of this build. Defaults to the CARGO_PKG_VERSION environment variable if not specified.
SURREAL_EXPERIMENTAL_BEARER_ACCESSfalseEnable 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_SIZE1000The maximum number of keys that should be scanned at once for export queries.
SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT50000Specifies the buffer limit for external sorting.
SURREAL_FUNCTION_ALLOCATION_LIMIT20Used to limit allocation for builtin functions.
SURREAL_EXPERIMENTAL_GRAPHQLfalseEnables 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_SIZE4398046511104 (4 GiB)Maximum HTTP body size of the HTTP /ml endpoints
SURREAL_HTTP_MAX_SQL_BODY_SIZE1048576 (1 MiB)Maximum HTTP body size of the HTTP /sql endpoint
SURREAL_HTTP_MAX_RPC_BODY_SIZE4194304 (4 MiB)Maximum HTTP body size of the HTTP /rpc endpoint
SURREAL_HTTP_MAX_KEY_BODY_SIZE16384 (16 KiB)Maximum HTTP body size of the HTTP /key endpoints
SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE1024 (1 KiB)Maximum HTTP body size of the HTTP /signup endpoint.
SURREAL_HTTP_MAX_SIGNIN_BODY_SIZE1024 (1 KiB)The maximum HTTP body size of the HTTP /signin endpoints
SURREAL_HTTP_MAX_IMPORT_BODY_SIZE4398046511104 (4 GiB)Maximum HTTP body size of the HTTP /import endpoints
SURREAL_INSECURE_FORWARD_ACCESS_ERRORSfalseForward all signup/signin/authenticate query errors to a client performing authentication. Do not use in production.
SURREAL_MAX_CONCURRENT_TASKS64Specifies how many concurrent jobs can be buffered in the worker channel.
SURREAL_MAX_OBJECT_PARSING_DEPTH10Specifies how deep the parser will parse nested objects and arrays in a query.
SURREAL_MAX_QUERY_PARSING_DEPTH20Specifies how deep the parser will parse recursive queries (queries within queries).
SURREAL_MAX_STREAM_BATCH_SIZE1000The maximum number of keys that should be fetched when streaming range scans in a Scanner.
SURREAL_NORMAL_FETCH_SIZE50The maximum number of keys that should be scanned at once in general queries.
SURREAL_RUNTIME_MAX_BLOCKING_THREADS512Number of threads which can be started for blocking operations.
SURREAL_RUNTIME_STACK_SIZE10485760 (10 MiB)Runtime thread memory stack size. Stack size is doubled if compiled from source in Debug mode.
SURREAL_SCRIPTING_MAX_MEMORY_LIMIT262144 (256 KiB)Maximum stack size of the JavaScript function runtime.
SURREAL_SCRIPTING_MAX_STACK_SIZE2097152 (2 MiB)Maximum memory limit of the JavaScript function runtime.
SURREAL_SURREALCS_CONNECTION_POOL_SIZENumber of CPUs on the current deviceSize of the SurrealCS connection pool.
SURREAL_TRANSACTION_CACHE_SIZE10000Specifies the number of items which can be cached within a single transaction.
SURREAL_WEBSOCKET_MAX_CONCURRENT_REQUESTS24Maximum concurrent tasks that can be handled on each WebSocket.
SURREAL_WEBSOCKET_MAX_FRAME_SIZE16777216 (16 MiB)Maximum WebSocket frame size.
SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE134217728 (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:

SURREAL_CAPS_ALLOW_NET SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete" surreal start --user root --pass root
Environment variableFor command(s)Command argDetails
SURREAL_AUTH_LEVELsurreal export, import, sqlauth-levelAuthentication level to use when connecting.
SURREAL_BINDsurreal startbindThe hostname or IP address(es) to listen for connections on.
SURREAL_CAPS_ALLOW_ALLsurreal startallow-allAllow all capabilities.
SURREAL_CAPS_ALLOW_FUNCsurreal startallow-funcsAllow execution of all or certain functions.
SURREAL_CAPS_ALLOW_GUESTSsurreal startallow-guestsAllow guest users to execute queries.
SURREAL_CAPS_ALLOW_NETsurreal startallow-netAllow all or certain outbound network access.
SURREAL_CAPS_ALLOW_SCRIPTsurreal startallow-scriptingAllow execution of embedded scripting functions.
SURREAL_CAPS_DENY_ALLsurreal startdeny-allDeny all capabilities.
SURREAL_CAPS_DENY_FUNCsurreal startdeny-funcsDeny execution of all or certain functions.
SURREAL_CAPS_DENY_GUESTSsurreal startdeny-guestsDeny guest users to execute queries.
SURREAL_CAPS_DENY_NETsurreal startdeny-netDeny all or certain outbound access paths.
SURREAL_CAPS_DENY_SCRIPTsurreal startdeny-scriptingDeny execution of embedded scripting functions.
SURREAL_CLIENT_IPsurreal startclient-ipThe method of detecting the client’s IP address.
SURREAL_DATABASEsurreal export, import, sqldatabaseThe database selected for the operation.
SURREAL_HIDE_WELCOMEsurreal sqlhide-welcomeWhether to show welcome message.
SURREAL_KEYsurreal startkeyEncryption key to use for on-disk encryption.
SURREAL_KVS_CAsurreal startkvs-caPath to the CA file used when connecting to the remote KV store.
SURREAL_KVS_KEYsurreal startkvs-keyPath to the private key file used when connecting to the remote KV store.
SURREAL_KVS_CERTsurreal startkvs-certPath to the certificate file used when connecting to the remote KV store.
SURREAL_LOGsurreal fix, startlogThe logging level for the database server.
SURREAL_NAMEsurreal ml exportnameThe name of the model.
SURREAL_NAMESPACEsurreal export, import, sqlnamespaceThe namespace selected for the operation.
SURREAL_NO_BANNERsurreal startno-bannerWhether to hide the startup banner.
SURREAL_NO_IDENTIFICATION_HEADERSsurreal startno-identification-headersWhether to suppress the server name and version headers.
SURREAL_PASSsurreal export, import, sql, startpassword, passDatabase authentication password to use when connecting.
SURREAL_PATHsurreal fix, startpathDatabase path used for storing data.
SURREAL_QUERY_TIMEOUTsurreal startquery-timeoutThe maximum duration that a set of statements can run for.
SURREAL_STRICTstartstrictWhether strict mode is enabled on this database instance.
SURREAL_TEMPORARY_DIRECTORYsurreal starttemporary-directorySets the directory for storing temporary database files
SURREAL_TICK_INTERVALsurreal starttick-intervalThe interval at which to run node agent tick (including garbage collection).
SURREAL_TOKENsurreal export, import, sqltokenAuthentication token in JWT format to use when connecting.
SURREAL_TRANSACTION_TIMEOUTsurreal starttransaction-timeoutThe maximum duration that any single transaction can run for.
SURREAL_UNAUTHENTICATEDsurreal startunauthenticatedWhether to allow unauthenticated access.
SURREAL_USERsurreal export, import, sql, startusername, userDatabase authentication username to use when connecting.
SURREAL_VERSIONsurreal ml exportnameThe version of the model.
SURREAL_WEB_CRTsurreal startweb-crtPath to the certificate file for encrypted client connections.
SURREAL_WEB_KEYsurreal startweb-keyPath 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 variableDefault valueNotes
SURREAL_FOUNDATIONDB_TRANSACTION_MAX_RETRY_DELAY500
SURREAL_FOUNDATIONDB_TRANSACTION_TIMEOUT5000
SURREAL_FOUNDATIONDB_TRANSACTION_RETRY_LIMIT5

RocksDB

Environment variableDefault valueNotes
SURREAL_ROCKSDB_THREAD_COUNTNumber of CPUs on machine
SURREAL_ROCKSDB_WRITE_BUFFER_SIZE268435456 (256 MiB)
SURREAL_ROCKSDB_TARGET_FILE_SIZE_BASE536870912 (512 MiB)
SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER32
SURREAL_ROCKSDB_MIN_WRITE_BUFFER_NUMBER_TO_MERGE4
SURREAL_ROCKSDB_ENABLE_PIPELINED_WRITEStrue
SURREAL_ROCKSDB_ENABLE_BLOB_FILEStrue
SURREAL_ROCKSDB_MIN_BLOB_SIZE4096
SURREAL_ROCKSDB_KEEP_LOG_FILE_NUM20
© SurrealDB GitHub Discord Community Cloud Features Releases Install