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 should 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 must 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 --auth-level root --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, all NAMESPACE, DATABASE, and TABLE definitions will not be created 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

SurrealKV is an embedded ACID-compliant key-value storage engine with built-in versioning, that allows for historical or temporal querying. It is built entirely in Rust - like the rest of SurrealDB.

Since SurrealKV supports historical/temporal querying, you can user the VERSION clause when selecting or creating data to access historical data. Learn more in the SurrealQL documentation.

Important

Although included in SurrealDB 2.0, the storage engine itself is considered beta, and may require additional development and testing before it is ready for production use.

To start a SurrealDB instance with SurrealKV, run the following command:

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

.d8888b.                                             888 8888888b.  888888b.
d88P  Y88b                                            888 888  'Y88b 888  '88b
Y88b.                                                 888 888    888 888  .88P
 'Y888b.   888  888 888d888 888d888  .d88b.   8888b.  888 888    888 8888888K.
    'Y88b. 888  888 888P'   888P'   d8P  Y8b     '88b 888 888    888 888  'Y88b
      '888 888  888 888     888     88888888 .d888888 888 888    888 888    888
Y88b  d88P Y88b 888 888     888     Y8b.     888  888 888 888  .d88P 888   d88P
 'Y8888P'   'Y88888 888     888      'Y8888  'Y888888 888 8888888P'  8888888P'


2024-09-12T13:23:48.714786Z  INFO surreal::env: Running 2.0.0-beta.2 for macos on aarch64
2024-09-12T13:23:48.714846Z  INFO surrealdb::core::kvs::tr: Starting kvs store at surrealkv://mydb
2024-09-12T13:23:48.716302Z  INFO surrealdb::core::kvs::tr: Started kvs store at surrealkv://mydb

Performance characteristics and trade-offs

Strengths

SurrealKV offers several notable performance advantages:

From a latency perspective, the system provides constant-time retrieval operations through direct offset lookups. Write operations are primarily bound by sequential I/O performance, and the system maintains minimal disk seeks during normal operation.

In terms of throughput properties, SurrealKV excels through its sequential write patterns that maximize I/O bandwidth utilization. The system’s concurrent read operations effectively scale with available CPU cores, while range queries are optimized through the trie’s prefix-based organization.

The recovery semantics are robust and predictable. During initial startup, the system performs a full segment scan to rebuild the index. Recovery and repair times scale proportionally with the total segment size and last active segment size, respectively. Data integrity is maintained through CRC verification during recovery. The system handles partial writes effectively by using CRC32 calculations from record fields to detect truncated writes, identifying and truncates incomplete records during recovery, and ensuring transaction logs are recovered to the last valid record boundary.

Operationally, SurrealKV offers significant advantages. The compaction process runs concurrently with normal operations, and the append-only format makes replication procedures straightforward.

Limitations

SurrealKV does have some important limitations to consider:

Memory management is a key consideration, as the index must reside in memory. Memory usage scales with the number of unique keys, key size distribution, and the number of versions per key.

Write amplification is another factor to consider. Each update creates a new version, requiring periodic compaction. During compaction, space usage temporarily increases.

Range query performance varies depending on several factors: key distribution, version history depth, and range size. Large ranges may require multiple disk reads to complete.

From an operational standpoint, regular compaction is necessary for space reclamation. System restart time increases with log size, and high-cardinality keyspaces can create memory pressure.

Performance implications

SurrealKV is particularly well-suited for certain use cases. It performs optimally with write-intensive workloads, point query dominated patterns, prefix-based access patterns, and time-series data with version tracking.

However, some scenarios may not be ideal for SurrealKV. These include memory-constrained environments, very large key spaces, scan-heavy workloads, and situations involving random updates to large datasets.

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

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

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

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:
  -l, --log <LOG>
          The logging level for the database server
          
          [env: SURREAL_LOG=]
          [default: info]
          [possible values: none, full, error, warn, info, debug, trace]

      --no-banner
          Whether to hide the startup banner
          
          [env: SURREAL_NO_BANNER=]

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

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

      --temporary-directory <TEMPORARY_DIRECTORY>
          Sets the directory for storing temporary database files
          
          [env: SURREAL_TEMPORARY_DIRECTORY=]

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.