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

Positional argument

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 non-persistent 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://

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.

The surreal start command starts the server as a whole without regard to individual namespaces or databases.

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. A particular namespace and database can be specified using the surreal sql command, as seen below.

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

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.

The above example also selects a namespace and database so that you can immediately start entering queries if you wish. See the documentation of the surreal sql command for more information.

Strict mode

SurrealDB supports the ability to startup in strict mode. When running in strict mode, no NAMESPACE, DATABASE, or TABLE definitions will be enacted automatically when data is inserted. Instead, if the selected namespace, database, or table has not been specifically defined, then the query will return an error.

surreal start --strict --log debug memory

RocksDB

To start a SurrealDB instance with RocksDB as the storage engine include the rocksdb:// prefix in the path argument.

surreal start -u root -p root rocksdb://mydb

SurrealKV (Beta)

Available since: v2.0.0

To start a SurrealDB instance with SurrealKV as the storage engine, include the surrealkv:// prefix in the path argument.

surreal start -u root -p root surrealkv://mydb

While SurrealKV supports historical/temporal querying using the VERSION clause when selecting or creating data, you must explicitly opt in to this using the surrealkv+versioned:// prefix in the path argument.

surreal start -u root -p root surrealkv+versioned://mydb

You can learn more about SurrealKV and how it compares to RocksDB in the SurrealKV documentation.

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

Available since: v2.0.0

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.

Note

We recommend enabling authentication when running SurrealDB in production or in publicly exposed ways. Failure to do so may result in unauthorized access.

To start a SurrealDB instance in unauthenticated mode, run the following command:

surreal start --unauthenticated

Identification headers

Available since: v2.0.0

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

Available since: v2.2.0

To use experimental capabilities, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to the experimental capability you want to allow.

For example, to use record references, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to record_references.

SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references,graphql" surreal start

or, using the --allow-experimental flag:

surreal start --allow-experimental record_references

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

SURREAL_CAPS_ALLOW_EXPERIMENTAL="record_references, graphql, define_api" surreal start
surreal start --allow-experimental record_references,graphql,define_api

Note

The experimental capability is completely hidden in the CLI help command, and --allow-all will not enable the experimental capabilities by default.

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

Using environment variables

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.

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.

For more on the environment variables available for CLI commands or SurrealDB instances in general, see the environment variables page.

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

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

  -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 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: 10s]

  -s, --strict
          Whether strict mode is enabled on this database instance
          
          [env: SURREAL_STRICT=]

      --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
          
          [env: SURREAL_CLIENT_IP=]
          [default: socket]

          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

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