The start command starts a SurrealDB server in memory, on disk, or in a distributed setup, using the installed surreal CLI.
This page is divided into two views: the details of the surreal db start command itself, and a builder that creates a command based on the options you choose.
surreal db start [OPTIONS] [PATH]The root user from --username and --password, and the default namespace and database, are created only when the datastore is new, and are stored in it. Starting the same datastore again with other values changes nothing: the existing root user keeps its password, and no new namespace or database is created. To change the password of an existing root user, use ALTER USER or DEFINE USER OVERWRITE.
surreal db start has more options than any other subcommand, and the table above covers the ones described on this page. The remaining groups - database tuning, datastore TLS, HTTP server, capabilities, and logging - are listed in full in the command help below, and mapped to their variables on the environment variables page.
Three of the flags above are documented in more detail elsewhere: --postgres-bind exposes the Postgres wire protocol, --mysql-bind exposes the MySQL wire protocol, and the --durable-* flags are explained under Durable HTTP RPC sessions. From SurrealDB 3.1, the Forwarded value for --client-ip reads the RFC 7239 Forwarded header.
The --query-timeout flag in the command help sets the maximum duration that a batch of statements can run for, and is off by default. From 3.3.0 the same value is also a hard wall-clock limit on each HTTP /sql, /gql and /graphql request and on each RPC method call. An HTTP /sql or /gql request that exceeds it is answered with 504 Gateway Timeout, and a /graphql request with a GraphQL error. The begin, commit and cancel RPC methods are exempt, but the calls made inside the transaction they control are still limited individually. See SURREAL_QUERY_TIMEOUT.
Getting started
This example will show how to host a SurrealDB server with the surreal db start command, and then access the Surreal DB server using the surreal db sql command.
To start a SurrealDB server, run the surreal db start command, using the options below. This example stores the database in memory, with a username and password, hosted at 127.0.0.1:8000 (the default location).
surreal db start memory --user my_username --pass my_passwordThe server is actively running, and can be left alone until you want to stop hosting the SurrealDB server.
The message "Started web server on 127.0.0.1:8000", indicates where the server is being hosted and can be accessed by clients. The location 127.0.0.1:8000 is the default, and can be manually changed by specifying the --bind option of the surreal db start command.
To access the SurrealDB server that you have started hosting, open a new terminal which will act as the client, while the previous terminal is still running the surreal db start command described above. This is done using a separate surreal db sql command. Ensure that the hosting location indicated by the output of the surreal db start command is passed to the --endpoint argument, and that you specify the same --username and --password as in the surreal db start command.
A particular namespace and database can be specified at this point, as seen below.
surreal db sql --endpoint http://127.0.0.1:8000 --namespace my_namespace \
--database my_database --username my_username --password my_passwordPositional argument
FoundationDB support was removed in SurrealDB 3.0.0, so fdb:// paths are only accepted by 2.x. Migrate a FoundationDB deployment to one of the backends below before upgrading.
In the surreal db start command, the path argument is used to specify the location of the database. If no argument is given, the default of memory for storage in memory is assumed.
Arguments for persistent backends are a combination of the backend name, a : or ://, and an address or filename - for example surrealkv://mydb or surrealkv:database. The available backends are:
memory(or no argument) for in-memory storagesurrealkvfor SurrealKV, the on-disk backendtikvfor TiKV, insurreal-tikv, a separate build of the server. Thesurrealbinary and thesurrealdb/surrealdbcontainer images do not include TiKV, and stop with an error on atikv://path.
SurrealDB 4.0 removed the rocksdb and indxdb backends. The rocksdb:// and indxdb:// schemes are kept as deprecated spellings of surrealkv://: a path that names either is opened with SurrealKV, and the server logs a warning to use surrealkv:// instead. Starting the server on a RocksDB data directory, with either scheme, converts it to SurrealKV. See Moving a RocksDB database to SurrealKV.
Absolute vs. relative paths
The datastorage flavour (surrealkv, tikv, etc.) followed by : or :// will be recognised as a relative path, which is resolved from the directory you run surreal db start in. Running surreal db start surrealkv:mydb from /home/ann/projects stores the data in /home/ann/projects/mydb, and running the same command from another directory creates a new, empty database there. Use an absolute path for a server that is started from different places, such as by a service manager. Any other number of slashes such as surrealkv:/path or surrealkv:///path will be interpreted as an absolute path. As a short absolute path of this nature will often require elevated permissions, the output for this command may end in this sort of error.
There was a problem with the datastore: IO error: Read-only file system (os error 30)If you see this error without having intended to start the server on an absolute path, it is likely that the path passed in unintentionally contains either one slash or more than two slashes.
Be sure not to point two storage backends at the same location. As storage is entirely delegated to the backend, the CLI is not aware of the structure of the data itself. While each backend uses its own file names and directory structure to store data, it is possible that data overwrite or other issues may occur. The one deliberate exception is a RocksDB directory from before 4.0, which SurrealKV converts when it opens it.
TiKV (tikv://…) is supported for local multi-node experimentation with the Community edition. From SurrealDB 4.0 it needs the separate surreal-tikv build. See TiKV runs from a separate build. Production multi-node HA uses distributed storage on SurrealDB Cloud Scale or SurrealDB Enterprise. See Run a multi-node cluster and Deployment. To provision and scale those instances from a script rather than a browser, see surreal cloud.
Datastore configuration
Configuring a datastore is done by passing in a string that begins with the datastore name, a path if persistent storage is needed, and optional parameters. Some examples:
surreal db start --user root --pass secret "surrealkv://path/to/db?versioned=true&sync=every&retention=30d"
surreal db start --user root --pass secret "mem://tmp/data?aol=sync&snapshot=60s&sync=5s"Each database store supports different parameters.
Supported parameters for Memory (SurrealMX)
The memory backend does not support versioned queries. From 3.3.0 a server started on it with versioned=true or a non-zero retention, whether through the parameters or the matching SURREAL_DATASTORE_VERSIONED and SURREAL_DATASTORE_RETENTION environment variables, fails to start. versioned=false and a zero retention are accepted. To use the VERSION clause, start the server on SurrealKV instead.
aol(never,sync, orasync), for writing changes to an append-only log filesnapshot(a duration string, e.g.60s), for periodically writing a snapshot of the database to the file systemsync(never,every, or a duration string like5s), for specifying when to flush the append-only log file to the file systemnever- (default) leave flushing to the OS (least durable)every- sync on every commit (most durable)interval- periodic background flushing at the given interval
Persistence for the memory backend is used for the following:
Append-Only Log (AOL) - Synchronous/asynchronous modes for durability
Snapshots - Periodic full database state capture
Data Recovery - Automatic recovery from snapshots + AOL on startup
AOL Truncation - Automatic cleanup after snapshots
Supported parameters for SurrealKV
versioned(trueorfalse)retention(a duration string, e.g.30d,24h,30m)sync(never,every, or a duration string like5s), for specifying when to flush the database to the file systemevery- (default) sync each transaction to disk before it is confirmed (most durable)never- leave flushing to the OS (least durable)interval- periodic background flushing at the given interval
With sync=every, a commit becomes visible to other transactions only once it is durable on disk.
Storage engine settings
Any setting of the storage engine can also go in the path, named without its SURREAL_<ENGINE>_ prefix. For SurrealKV, block_cache_capacity sets SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY and max_memtable_size sets SURREAL_SURREALKV_MAX_MEMTABLE_SIZE. This caps the block cache at 256 MiB and each memtable at 64 MiB:
surreal db start --user root --pass secret "surrealkv://path/to/db?block_cache_capacity=268435456&max_memtable_size=67108864"A setting in the path takes precedence over the same setting made by an environment variable. At startup the server logs the values SurrealKV uses, as in Setting block cache capacity: 268435456, so the log shows which one applied.
Authentication
When starting a SurrealDB instance, authentication is enabled by default, and your user credentials will be required to connect. If you are starting a new instance, the user credentials you use to run the start command will define a new root user with the OWNER role.
surreal db start --user root --password secretUnauthenticated mode
We recommend enabling authentication when running SurrealDB in production or in publicly exposed ways. Failure to do so may result in unauthorised access.
Using the --unauthenticated flag, you can also start a SurrealDB instance in unauthenticated mode. By doing so, authentication will be disabled. In this mode, any guest user is considered to have the same permissions as a root user with the OWNER role.
To start a SurrealDB instance in unauthenticated mode, run the following command:
surreal db start --unauthenticatedUsing environment variables
Most of the flags above have a corresponding environment variable.
For example, the --temporary-directory flag can be configured with the SURREAL_TEMPORARY_DIRECTORY environment variable instead.
When using the surreal db start command, you can also use environment variables to set the values for the command-line flags. This is useful when you want to set the values for the command-line flags without having to pass them directly on the command line.
For more on the environment variables available for CLI commands or SurrealDB instances in general, see the environment variables page.
Stopping the server
To stop the server, press Ctrl+C in its terminal, or send it SIGTERM (as docker stop, kill and systemctl stop do). Either signal starts a graceful shutdown: the server stops accepting connections, the storage engine writes out what it holds in memory, and the process exits with status 0.
WARN surrealdb::net: SIGINT received. Waiting for a graceful shutdown. A second signal will force an immediate shutdown.
INFO surrealdb::net: Web server stopped. Bye!A second signal during the shutdown stops the process at once, without waiting. On a persistent backend such as SurrealKV, data from committed transactions is kept either way, subject to the backend's sync setting. On the in-memory backend, all data is lost when the process stops unless persistence is configured.
Enabling capabilities
If using SurrealDB Cloud, capabilities can be set from SurrealDB Studio or with surreal cloud.
Capabilities arguments such as allow-scripting or deny-net can also be passed into the surreal db start command. These arguments, the order in which they are evaluated, and other notes on security are presented in detail in a separate page on capabilities. From SurrealDB 4.0, the server logs the capabilities it starts with, and logs a warning at startup for --allow-all, guest access, scripting and network access to every target, as described in Capabilities in the startup log.
A production-oriented example of the surreal db start command that begins with the --deny-all flag and only thereafter sets which capabilities will be allowed:
surreal db start --deny-all --allow-funcs "array, string, crypto::argon2, http::get" --allow-net api.example.comStrict mode
Versions before SurrealDB 3.0 contained a flag to start the entire server in strict mode. When running in strict mode, no NAMESPACE, DATABASE, or TABLE definitions were enacted automatically when data is inserted. Any queries would return an error if the selected namespace, database, or table were not specifically defined in advance.
surreal db start --strict --log debug memorySince SurrealDB 3.0, strict mode is now enacted on the database level via a DEFINE DATABASE statement.
DEFINE DATABASE my_anything_goes_db;
DEFINE DATABASE my_strict_db STRICT;Experimental capabilities
The experimental capability is completely hidden in the CLI help command, and --allow-all will not enable the experimental capabilities by default.
To use experimental capabilities, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to the experimental capability you want to allow.
For example, to use Surrealism extensions, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to surrealism - or pass it in via the --allow-experimental flag.
# Allow experimental via an env var
SURREAL_CAPS_ALLOW_EXPERIMENTAL=surrealism surreal db start
# Allow experimental via a flag
surreal db start --allow-experimental surrealismMultiple experimental capabilities can be enabled by separating them with a comma.
SURREAL_CAPS_ALLOW_EXPERIMENTAL=surrealism,kvexport surreal db start
surreal db start --allow-experimental surrealism,kvexport--allow-experimental accepts several values, so a storage path written after it is read as one more capability name, and the server refuses to start with invalid experimental target name. Join the value to the flag with =, or put the path before the flag:
surreal db start --allow-experimental=surrealism,kvexport surrealkv:mydatabase.db
surreal db start surrealkv:mydatabase.db --allow-experimental surrealism,kvexport Experimental capabilities are enforced on the server for remote clients. If you use surreal db sql against ws:// or http://, configure flags here - not only on the REPL. See Capabilities and remote connections.
From 3.3.0, ISO GQL is enabled by default and no longer uses an experimental capability. From 4.0, --allow-experimental gql is refused with invalid experimental target name and the server does not start, so remove gql from the list. On 3.3.x the tag is accepted and has no effect, and on 3.2.x it enables GQL.
From 4.0, buckets and file functions are available without an experimental capability. files is refused with invalid experimental target name in --allow-experimental, --deny-experimental, SURREAL_CAPS_ALLOW_EXPERIMENTAL and SURREAL_CAPS_DENY_EXPERIMENTAL, and the server does not start, so remove files from the list. Before 4.0, files was required to use buckets and files.
| Example feature/statement | Tag |
|---|---|
| DEFINE EXTENSION | surrealism |
The POST /kvexport HTTP route, which streams the stored keyspace to the root owner | kvexport |
Identification headers
By default, SurrealDB includes headers in the HTTP response that identify the server name and version. You can suppress these headers by using the --no-identification-headers flag.
surreal db start --no-identification-headersDurable HTTP RPC sessions
Available since: v3.2.2
Every client-attached session on the HTTP /rpc endpoint is stored in the datastore. A session survives a restart, and any node that shares the same storage can serve it, so a load-balanced deployment does not need sticky routing. Requests from several nodes on the same session can run at the same time: each request writes its changes back only if the stored session has not changed meanwhile, and otherwise merges them onto the newer copy.
A session expires between one and one and a half times --durable-session-ttl (default 24h) after its last request. An expired session is refused when it is loaded. A background task removes expired entries from the datastore (--durable-session-gc-interval, default 1h; set 0 to disable the sweep).
surreal db start --durable-session-ttl 12h surrealkv://mydbThe --durable-sessions flag and SURREAL_DURABLE_SESSIONS are still accepted so that existing configurations keep starting, but have no effect, and the server logs a deprecation warning. Each node keeps at most SURREAL_HTTP_MAX_ATTACHED_SESSIONS sessions attached through it.
The stored session includes its authentication state and is stored unencrypted in the datastore.
WebSocket connections keep in-memory sessions only. Durable sessions do not change WebSocket behaviour.
Further examples
As surreal db start is the command with by far the largest number of options, a few more examples will help give an idea of what sort of configurations are available.
An instance with a single root user, able to connect to the internet but unable to use three functions:
surreal db start --user root --pass secret --allow-net --deny-funcs "crypto::md5, http::post, http::delete"An instance with more verbose logging that uses SurrealKV as its storage engine:
surreal db start --log debug surrealkv:mydatabase.dbAn instance with all capabilities denied except a few functions and a single endpoint:
surreal db start --deny-all --allow-funcs "array, string, crypto::argon2, http::get" --allow-net api.example.comAn instance with a different default address, less verbose logging level, and ability to use JavaScript functions:
surreal db start --bind 0.0.0.0:2218 --log warn --allow-scriptingCommand help
To see the help information and usage instructions, in a terminal run the surreal db start --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the start command.
surreal db start --helpThe output of the above command:
Start the database server
Usage: surreal start [OPTIONS] [PATH]
Arguments:
[PATH]
Database path used for storing data
[env: SURREAL_PATH]
[default: memory]
Options:
--index-compaction-interval <INDEX_COMPACTION_INTERVAL>
[env: SURREAL_INDEX_COMPACTION_INTERVAL]
[default: 5s]
--async-event-interval <EVENT_PROCESSING_INTERVAL>
[env: SURREAL_ASYNC_EVENT_PROCESSING_INTERVAL]
[default: 5s]
--reclaim-interval <RECLAIM_INTERVAL>
[env: SURREAL_RECLAIM_INTERVAL]
[default: 60s]
-h, --help
Print help (see a summary with '-h')
Database:
--node-membership-refresh-interval <NODE_MEMBERSHIP_REFRESH_INTERVAL>
The interval at which to refresh node registration information
[env: SURREAL_NODE_MEMBERSHIP_REFRESH_INTERVAL]
[default: 3s]
--node-membership-check-interval <NODE_MEMBERSHIP_CHECK_INTERVAL>
The interval at which to process and archive inactive nodes
[env: SURREAL_NODE_MEMBERSHIP_CHECK_INTERVAL]
[default: 15s]
--node-membership-cleanup-interval <NODE_MEMBERSHIP_CLEANUP_INTERVAL>
The interval at which to process and cleanup archived nodes
[env: SURREAL_NODE_MEMBERSHIP_CLEANUP_INTERVAL]
[default: 300s]
--changefeed-gc-interval <CHANGEFEED_GC_INTERVAL>
The interval at which to perform changefeed garbage collection
[env: SURREAL_CHANGEFEED_GC_INTERVAL]
[default: 30s]
--graph-fold-interval <GRAPH_FOLD_INTERVAL>
The interval at which to fold graph adjacency keys into packed blocks
[env: SURREAL_GRAPH_FOLD_INTERVAL]
[default: 5s]
--index-build-resume-interval <INDEX_BUILD_RESUME_INTERVAL>
The interval at which to resume index builds left unfinished by a crashed node (0 to disable)
[env: SURREAL_INDEX_BUILD_RESUME_INTERVAL]
[default: 30s]
--reclaim-grace <RECLAIM_GRACE>
Minimum age a removed namespace/database/index must reach before its data is physically reclaimed (snapshot-safety grace;
effective value is max(this, --tikv-gc-lifetime))
[env: SURREAL_RECLAIM_GRACE]
[default: 10m]
--tikv-gc-interval <TIKV_GC_INTERVAL>
The interval at which the TiKV MVCC garbage collector runs
[env: SURREAL_TIKV_GC_INTERVAL]
[default: 10m]
--tikv-gc-lifetime <TIKV_GC_LIFETIME>
How far behind the current TSO the TiKV GC safepoint is allowed to sit
[env: SURREAL_TIKV_GC_LIFETIME]
[default: 10m]
--tikv-lock-cleanup-interval <TIKV_LOCK_CLEANUP_INTERVAL>
The interval at which TiKV stale transactional locks are resolved
[env: SURREAL_TIKV_LOCK_CLEANUP_INTERVAL]
[default: 60s]
--durable-session-ttl <DURABLE_SESSION_TTL>
How long an attached HTTP RPC session survives without being used: it expires between one and one and a half times this long after
its last request. Attached sessions are stored in the datastore, including their authentication state, so they survive restarts
and any node can serve them
[env: SURREAL_DURABLE_SESSION_TTL]
[default: 24h]
--durable-session-gc-interval <DURABLE_SESSION_GC_INTERVAL>
The interval at which expired attached HTTP RPC sessions are purged from the datastore (0 to disable). An expired session is
refused whether or not it has been purged
[env: SURREAL_DURABLE_SESSION_GC_INTERVAL]
[default: 1h]
--query-timeout <QUERY_TIMEOUT>
The maximum duration that a set of statements can run for
[env: SURREAL_QUERY_TIMEOUT]
--transaction-timeout <TRANSACTION_TIMEOUT>
The maximum duration that any single transaction can run for
[env: SURREAL_TRANSACTION_TIMEOUT]
--startup-operation-timeout <STARTUP_OPERATION_TIMEOUT>
The maximum duration that each built-in startup datastore operation can retry for
[env: SURREAL_STARTUP_OPERATION_TIMEOUT]
[default: 60s]
Authentication:
-u, --username <USERNAME>
The username for the initial database root user. Only if no other root user exists
[env: SURREAL_USER]
[alias: --user]
-p, --password <PASSWORD>
The password for the initial database root user. Only if no other root user exists
[env: SURREAL_PASS]
[alias: --pass]
--unauthenticated
Whether to allow unauthenticated access
[env: SURREAL_UNAUTHENTICATED]
Datastore connection:
--kvs-ca <KVS_CA>
Path to the CA file used when connecting to the remote KV store
[env: SURREAL_KVS_CA]
--kvs-crt <KVS_CRT>
Path to the certificate file used when connecting to the remote KV store
[env: SURREAL_KVS_CRT]
--kvs-key <KVS_KEY>
Path to the private key file used when connecting to the remote KV store
[env: SURREAL_KVS_KEY]
HTTP server:
--web-crt <WEB_CRT>
Path to the certificate file for encrypted client connections
[env: SURREAL_WEB_CRT]
--web-key <WEB_KEY>
Path to the private key file for encrypted client connections
[env: SURREAL_WEB_KEY]
--client-ip <CLIENT_IP>
The method of detecting the client's IP address
Possible values:
- none: Don't use client IP
- socket: Raw socket IP
- CF-Connecting-IP: Cloudflare connecting IP
- Fly-Client-IP: Fly.io client IP
- True-Client-IP: Akamai, Cloudflare true client IP
- X-Real-IP: Nginx real IP
- X-Forwarded-For: Industry standard header used by many proxies
- Forwarded: RFC 7239 `Forwarded` header; the first `for=` parameter is used
[env: SURREAL_CLIENT_IP]
[default: socket]
-b, --bind <LISTEN_ADDRESSES>
The hostname or IP address to listen for connections on
[env: SURREAL_BIND]
[default: 127.0.0.1:8000]
--no-identification-headers
Whether to suppress the server name and version headers
[env: SURREAL_NO_IDENTIFICATION_HEADERS]
--allow-origin <ALLOW_ORIGIN>
The allowed origins for CORS requests. Defaults to allow all origins
[env: SURREAL_ALLOW_ORIGIN]
--cookie-auth
Issue the access token as an HttpOnly cookie on request, and accept it from the allowed origins. Requires --allow-origin. The
cookie is Secure, so a browser stores it only over HTTPS or on a loopback address
[env: SURREAL_COOKIE_AUTH]
Postgres server:
--postgres-bind <POSTGRES_BIND>
The hostname or IP address to listen for Postgres wire protocol connections on
[env: SURREAL_POSTGRES_BIND]
MySQL server:
--mysql-bind <MYSQL_BIND>
The hostname or IP address to listen for MySQL wire protocol connections on
[env: SURREAL_MYSQL_BIND]
Capabilities:
-A, --allow-all
Allow all capabilities except for those more specifically denied
[env: SURREAL_CAPS_ALLOW_ALL]
--allow-scripting
Allow execution of embedded scripting functions
[env: SURREAL_CAPS_ALLOW_SCRIPT]
--allow-guests
Allow guest users to execute queries
[env: SURREAL_CAPS_ALLOW_GUESTS]
--allow-funcs [<ALLOW_FUNCS>...]
Allow execution of all functions except for functions that are specifically denied. Alternatively, you can provide a
comma-separated list of function names to allow
Specifically denied functions and function families prevail over any other allowed function execution.
Function names must be in the form <family>[::<name>]. For example:
- 'http' or 'http::*' -> Include all functions in the 'http' family
- 'http::get' -> Include only the 'get' function in the 'http' family
[env: SURREAL_CAPS_ALLOW_FUNC]
--allow-arbitrary-query [<ALLOW_ARBITRARY_QUERY>...]
Allow execution of arbitrary queries by certain user groups except when specifically denied. Alternatively, you can provide a
comma-separated list of user groups to allow
Specifically denied user groups prevail over any other allowed user group.
User groups must be one of "guest", "record" or "system".
[env: SURREAL_CAPS_ALLOW_ARBITRARY_QUERY]
--allow-eval-query [<ALLOW_EVAL_QUERY>...]
Allow the eval::surql / eval::gql functions to be invoked by certain user groups. Provide a comma-separated list of user groups to
allow. This is an additive gate on top of arbitrary-query: an eval invocation must also satisfy the arbitrary-query capability.
Specifically denied user groups prevail over any other allowed user group.
User groups must be one of "guest", "record" or "system".
Denied for everyone by default (even under --allow-all); must be explicitly enabled.
[env: SURREAL_CAPS_ALLOW_EVAL_QUERY]
--allow-net [<ALLOW_NET>...]
Allow all outbound network connections except for network targets that are specifically denied. Alternatively, you can provide a
comma-separated list of network targets to allow
Specifically denied network targets prevail over any other allowed outbound network connections.
Targets must be in the form of <host>[:<port>], *.<domain>[:<port>], <ipv4|ipv6>[/<mask>]. For example:
- 'surrealdb.com', '127.0.0.1' or 'fd00::1' -> Match outbound connections to these hosts on any port
- 'surrealdb.com:80', '127.0.0.1:80' or 'fd00::1:80' -> Match outbound connections to these hosts on port 80
- '*.surrealdb.com' -> Match outbound connections to any subdomain of surrealdb.com (such as 'api.surrealdb.com' or
'a.b.surrealdb.com', but not 'surrealdb.com' itself) on any port
- '*.surrealdb.com:443' -> Match outbound connections to any subdomain of surrealdb.com on port 443
- '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks
A wildcard is only allowed as the whole leftmost label and must be followed by a domain of at least two labels; it never matches
an IP address.
[env: SURREAL_CAPS_ALLOW_NET]
--allow-rpc [<ALLOW_RPC>...]
Allow all RPC methods to be called except for routes that are specifically denied. Alternatively, you can provide a
comma-separated list of RPC methods to allow.
[env: SURREAL_CAPS_ALLOW_RPC]
[default: ""]
--allow-http [<ALLOW_HTTP>...]
Allow all HTTP routes to be requested except for routes that are specifically denied. Alternatively, you can provide a
comma-separated list of HTTP routes to allow.
[env: SURREAL_CAPS_ALLOW_HTTP]
[default: ""]
--allow-mcp [<ALLOW_MCP>...]
Allow all MCP tools to be called except for tools that are specifically denied. Alternatively, you can provide a comma-separated
list of MCP tool names to allow.
[env: SURREAL_CAPS_ALLOW_MCP]
[default: ""]
-D, --deny-all
Deny all capabilities except for those more specifically allowed
[env: SURREAL_CAPS_DENY_ALL]
--deny-scripting
Deny execution of embedded scripting functions
[env: SURREAL_CAPS_DENY_SCRIPT]
--deny-guests
Deny guest users to execute queries
[env: SURREAL_CAPS_DENY_GUESTS]
--deny-funcs [<DENY_FUNCS>...]
Deny execution of all functions except for functions that are specifically allowed. Alternatively, you can provide a
comma-separated list of function names to deny.
Specifically allowed functions and function families prevail over a general denial of function execution.
Function names must be in the form <family>[::<name>]. For example:
- 'http' or 'http::*' -> Include all functions in the 'http' family
- 'http::get' -> Include only the 'get' function in the 'http' family
[env: SURREAL_CAPS_DENY_FUNC]
--deny-arbitrary-query [<DENY_ARBITRARY_QUERY>...]
Deny execution of arbitrary queries by certain user groups except when specifically allowed. Alternatively, you can provide a
comma-separated list of user groups to deny
Specifically allowed user groups prevail over a general denial of user group.
User groups must be one of "guest", "record" or "system".
[env: SURREAL_CAPS_DENY_ARBITRARY_QUERY]
--deny-eval-query [<DENY_EVAL_QUERY>...]
Deny the eval::surql / eval::gql functions for certain user groups. Provide a comma-separated list of user groups to deny.
Specifically denied user groups prevail over any allowed user group.
User groups must be one of "guest", "record" or "system".
[env: SURREAL_CAPS_DENY_EVAL_QUERY]
--deny-net [<DENY_NET>...]
Deny all outbound network connections except for network targets that are specifically allowed. Alternatively, you can provide a
comma-separated list of network targets to deny.
Specifically allowed network targets prevail over a general denial of outbound network connections.
Targets must be in the form of <host>[:<port>], *.<domain>[:<port>], <ipv4|ipv6>[/<mask>]. For example:
- 'surrealdb.com', '127.0.0.1' or 'fd00::1' -> Match outbound connections to these hosts on any port
- 'surrealdb.com:80', '127.0.0.1:80' or 'fd00::1:80' -> Match outbound connections to these hosts on port 80
- '*.surrealdb.com' -> Match outbound connections to any subdomain of surrealdb.com (such as 'api.surrealdb.com' or
'a.b.surrealdb.com', but not 'surrealdb.com' itself) on any port
- '*.surrealdb.com:443' -> Match outbound connections to any subdomain of surrealdb.com on port 443
- '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks
A wildcard is only allowed as the whole leftmost label and must be followed by a domain of at least two labels; it never matches
an IP address.
[env: SURREAL_CAPS_DENY_NET]
--deny-rpc [<DENY_RPC>...]
Deny all RPC methods from being called except for methods that are specifically allowed. Alternatively, you can provide a
comma-separated list of RPC methods to deny.
[env: SURREAL_CAPS_DENY_RPC]
--deny-http [<DENY_HTTP>...]
Deny all HTTP routes from being requested except for routes that are specifically allowed. Alternatively, you can provide a
comma-separated list of HTTP routes to deny.
[env: SURREAL_CAPS_DENY_HTTP]
--deny-mcp [<DENY_MCP>...]
Deny all MCP tools from being called except for tools that are specifically allowed. Alternatively, you can provide a
comma-separated list of MCP tool names to deny.
[env: SURREAL_CAPS_DENY_MCP]
--temporary-directory <TEMPORARY_DIRECTORY>
Sets the directory for storing temporary database files
[env: SURREAL_TEMPORARY_DIRECTORY]
--import-file <IMPORT_FILE>
Path to a SurrealQL file that will be imported when starting the server
[env: SURREAL_IMPORT_FILE]
--slow-log-threshold <SLOW_LOG_THRESHOLD>
The minimum execution time in milliseconds to trigger slow query logging
[env: SURREAL_SLOW_QUERY_LOG_THRESHOLD]
--slow-log-param-allow <SLOW_LOG_PARAM_ALLOW>...
A comma-separated list of parameter names to include in the params of slow query logs. No parameter value is logged unless its name is listed here
[env: SURREAL_SLOW_QUERY_LOG_PARAM_ALLOW]
--slow-log-param-deny <SLOW_LOG_PARAM_DENY>...
A comma-separated list of parameter names to leave out of the params of slow query logs, even if they are also allowed
[env: SURREAL_SLOW_QUERY_LOG_PARAM_DENY]
--default-namespace <DEFAULT_NAMESPACE>
The default namespace for a new instance
[env: SURREAL_DEFAULT_NAMESPACE]
--default-database <DEFAULT_DATABASE>
The default database for a new instance
[env: SURREAL_DEFAULT_DATABASE]
--no-defaults
Whether to disable default namespace and database creation
[env: SURREAL_NO_DEFAULTS]
--lazy-surrealism
Load Surrealism extensions lazily on first use instead of eagerly at startup
[env: SURREAL_LAZY_SURREALISM]
Logging:
-l, --log <LOG>
The logging level for the command-line tool
[env: SURREAL_LOG]
[default: info]
[possible values: none, full, error, warn, info, debug, trace]
--log-format <LOG_FORMAT>
The format for terminal log output
[env: SURREAL_LOG_FORMAT]
[default: text]
[possible values: text, json]
--log-socket <LOG_SOCKET>
Send logs to the specified host:port
[env: SURREAL_LOG_SOCKET]
--log-file-level <LOG_FILE_LEVEL>
Override the logging level for file output
[env: SURREAL_LOG_FILE_LEVEL]
[possible values: none, full, error, warn, info, debug, trace]
--log-otel-level <LOG_OTEL_LEVEL>
Override the logging level for OpenTelemetry output
[env: SURREAL_LOG_OTEL_LEVEL]
[possible values: none, full, error, warn, info, debug, trace]
--log-socket-level <LOG_SOCKET_LEVEL>
Override the logging level for unix socket output
[env: SURREAL_LOG_SOCKET_LEVEL]
[possible values: none, full, error, warn, info, debug, trace]
--log-socket-format <LOG_SOCKET_FORMAT>
The format for socket output
[env: SURREAL_LOG_SOCKET_FORMAT]
[default: text]
[possible values: text, json]
--log-file-enabled
Whether to enable log file output
[env: SURREAL_LOG_FILE_ENABLED]
--log-file-path <LOG_FILE_PATH>
The directory where log files will be stored
[env: SURREAL_LOG_FILE_PATH]
[default: logs]
--log-file-name <LOG_FILE_NAME>
The name of the log file
[env: SURREAL_LOG_FILE_NAME]
[default: surrealdb.log]
--log-file-format <LOG_FILE_FORMAT>
The format for log file output
[env: SURREAL_LOG_FILE_FORMAT]
[default: text]
[possible values: text, json]
--log-file-rotation <LOG_FILE_ROTATION>
The log file rotation interval
[env: SURREAL_LOG_FILE_ROTATION]
[default: daily]
[possible values: daily, hourly, never]