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_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_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_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. |
Command environment variables
Many of the arguments passed into the CLI can be set using these environment variables instead.
| 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
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 |