Start command

The start command starts a SurrealDB server in memory, on disk, or in a distributed setup.

BEFORE YOU START

Make sure you’ve installed SurrealDB — it should only take a second!

Command options

Arguments	Description
`-b` / `--bind`	Sets the hostname or IP address to listen for connections on
`--import-file`	Path to a SurrealQL (`.surql`) file that will be imported when starting the server
`-l` / `--log`	Sets the logging level for the database server
`-u` / `--user`	Sets master username for the database
`-p` / `--pass`	Sets master password for the database
`--unauthenticated`	Whether to allow unauthenticated access
`--no-identification-headers`	Whether to suppress the server name and version headers
`--temporary-directory`	Sets the directory for storing temporary database files
`--allow-experimental`	Sets the experimental capabilities to the experimental capabilities you want to allow.

Positional argument

Warning

FoundationDB support is deprecated in SurrealDB 3.0. Please plan to migrate to a supported storage backend.

In the surreal 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.

When using a path argument with SurrealDB, we recommend not using the file:// prefix. Instead, please use surrealkv:// or rocksdb:// as the path argument. If you are using the file:// prefix, the database will start with the following warning:

file:// is deprecated, please use surrealkv:// or rocksdb://

Absolute vs. relative paths

The datastorage flavour (rocksdb, surrealkv, etc.) followed by : or :// will be recognized as a relative path. Any other number of slashes such as rocksdb:/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.

Failed to create RocksDB directory: `Os { code: 30, kind: ReadOnlyFilesystem, message: "Read-only file system" }`.

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.

Arguments Description

path Sets the path for storing data. If no argument is given, the default of memory for non-persistent storage in memory is assumed. Arguments for persistent backends are a combination of the backend name, a : or ://, and an address or filename. Examples: surrealkv://mydb or rocksdb:database. memory (or no argument) for in-memory storage rocksdb for RocksDB surrealkv for SurrealKV indxdb for IndexedDB tikv for TiKV

Arguments	Description
`path`	Sets the path for storing data. If no argument is given, the default of `memory` for non-persistent storage in memory is assumed. Arguments for persistent backends are a combination of the backend name, a `:` or `://`, and an address or filename. Examples: `surrealkv://mydb` or `rocksdb:database`. `memory` (or no argument) for in-memory storage `rocksdb` for RocksDB `surrealkv` for SurrealKV `indxdb` for IndexedDB `tikv` for TiKV

Note

Be sure not to use multiple storage backends in the same location, such as rocksdb://path/to/database followed by surrealkv://path/to/database. 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.

Getting started

This example will show how to host a SurrealDB server with the surreal start command, and then access the Surreal DB server using the surreal sql command.

To start a SurrealDB server, run the surreal 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 start memory --user my_username --pass my_password

The server is actively running, and can be left alone until you want to stop hosting the SurrealDB server.

Note

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 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 start command described above. This is done using a separate surreal sql command. Ensure that the hosting location indicated by the output of the surreal start command is passed to the --endpoint argument, and that you specify the same --username and --password as in the surreal start command.

A particular namespace and database can be specified at this point, as seen below.

surreal sql --endpoint http://127.0.0.1:8000 --namespace my_namespace --database my_database --username my_username --password my_password

Using environment variables

Important

Most of the flags mentioned in the command output above also mention a corresponding environment variables.

For example, the --temporary-directory flag can be configured with the SURREAL_TEMPORARY_DIRECTORY environment variable instead.

When using the surreal 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.

Strict 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 start --strict --log debug memory

Since 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;

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 start --user root --pass secret "surrealkv://path/to/db?versioned=true&sync=every&retention=30d"
surreal start --user root --pass secret "mem://tmp/data?versioned=true&aol=sync&snapshot=60s&sync=5s"
surreal start --user root --pass secret "mem://?versioned=true"

Each database store supports different parameters.

Supported parameters for Memory (SurrealMX)

versioned (true or false)
retention (a duration string, e.g. 30d, 24h, 30m)
aol (never, sync, or async), for writing changes to an append-only log file
snapshot (a duration string, e.g. 60s), for periodically writing a snapshot of the database to the file system
sync (never, every, or a duration string like 5s), for specifying when to flush the append-only log file to the file system
- never - (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 (true or false)
retention (a duration string, e.g. 30d, 24h, 30m)
sync (never, every, or a duration string like 5s), for specifying when to flush the database to the file system
- every - (default) sync before completing and confirming each transaction (most durable)
- never - leave flushing to the OS (least durable)
- interval - periodic background flushing at the given interval

Supported paramaters for RocksDB

sync (never, every, or a duration string like 5s), for specifying when to flush the database to the file system
- every - (default) sync before completing and confirming each transaction (most durable)
- never - leave flushing to the OS (least durable)
- interval - periodic background flushing at the given interval

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 theOWNER role.

surreal start --user root -password root

Enabling capabilities

Note

If using SurrealDB Cloud, capabilities can be set using the Configure Instance panel on Surrealist.

Capabilities arguments such as allow-scripting or deny-net can also be passed into the surreal 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.

A production-oriented example of the surreal start command that begins with the --deny-all flag and only thereafter sets which capabilities will be allowed:

surreal start --deny-all --allow-funcs "array, string, crypto::argon2, http::get" --allow-net api.example.com:443

Unauthenticated mode

Note

We recommend enabling authentication when running SurrealDB in production or in publicly exposed ways. Failure to do so may result in unauthorized 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 start --unauthenticated

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 start --no-identification-headers

Experimental capabilities

Note

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 start

# Allow experimental via a flag
surreal start --allow-experimental surrealism

Multiple experimental capabilities can be enabled by separating them with a comma.

SURREAL_CAPS_ALLOW_EXPERIMENTAL=surrealism,files surreal start
surreal start --allow-experimental surrealism,files

Example feature/statement	Tag
DEFINE BUCKET	`files`
DEFINE MODULE	`surrealism`

Further examples

As surreal 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 start --user root --pass secret --allow-net --deny-funcs "crypto::md5, http::post, http::delete"

An instance with more verbose logging that uses RocksDB as its storage engine:

surreal start --log debug rocksdb:mydatabase.db

An instance with all capabilities denied except a few functions and a single endpoint:

surreal start --deny-all --allow-funcs "array, string, crypto::argon2, http::get" --allow-net api.example.com:443

An instance with a different default address, less verbose logging level, and ability to use JavaScript functions:

surreal start --bind 0.0.0.0:2218 --log warn --allow-scripting

Command help

To see the help information and usage instructions, in a terminal run the surreal start --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the start command.

surreal start --help

The 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:
      --no-banner
          Whether to hide the startup banner

          [env: SURREAL_NO_BANNER=]

      --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]

  -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]

      --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=]

Authentication:
  -u, --username <USERNAME>
          The username for the initial database root user. Only if no other root user exists

          [env: SURREAL_USER=]
          [aliases: --user]

  -p, --password <PASSWORD>
          The password for the initial database root user. Only if no other root user exists

          [env: SURREAL_PASS=]
          [aliases: --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

          [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=]

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-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>], <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
           - '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks

          [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: ]

  -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-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>], <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
           - '10.0.0.0/8' or 'fd00::/8' -> Match outbound connections to any host in these networks

          [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=]

      --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 slow query logs

          [env: SURREAL_SLOW_QUERY_LOG_PARAM_ALLOW=]

      --slow-log-param-deny <SLOW_LOG_PARAM_DENY>...
          A comma-separated list of parameter names to omit from slow query logs

          [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=]

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]