Back to top

Starting SurrealDB

Once you have installed SurrealDB, the surreal command-line tool is a single executable which can be used to backup, interact with, and run SurrealDB server instances. In this article we will start a SurrealDB server so that we can store and query data.

Run the following command in your terminal. It will display the options for starting a SurrealDB server instance.

user@localhost % surreal start -h
Start the database server

USAGE:
    surreal start [OPTIONS] [--] [path]

ARGS:
    <path>    Database path used for storing data [default: memory]

OPTIONS:
        --addr <addr>          The allowed networks for master authentication [default:
                               127.0.0.1/32]
    -b, --bind <bind>          The hostname or ip address to listen for connections on [default:
                               0.0.0.0:8000]
    -h, --help                 Print help information
    -k, --key <key>            Encryption key to use for on-disk encryption
        --kvs-ca <kvs-ca>      Path to the CA file used when connecting to the remote KV store
        --kvs-crt <kvs-crt>    Path to the certificate file used when connecting to the remote KV
                               store
        --kvs-key <kvs-key>    Path to the private key file used when connecting to the remote KV
                               store
    -l, --log <log>            The logging level for the database server [default: info] [possible
                               values: warn, info, debug, trace, full]
    -p, --pass <pass>          The master password for the database
    -s, --strict               Whether strict mode is enabled on this database instance
    -u, --user <user>          The master username for the database [default: root]
        --web-crt <web-crt>    Path to the certificate file for encrypted client connections
        --web-key <web-key>    Path to the private key file for encrypted client connections

Starting a single-node in-memory database

For the purposes of getting started with SurrealDB quickly, we will start an in-memory database which does not persist data on shutdown. This database is great for development and testing.

user@localhost % surreal start memory

The default logging level for the database server is info, resulting in any informational logs to be output to the standard output. To control the logging verbosity, specify the --log argument. The following command starts the database with trace level logging, resulting in most logs being output to the standard output.

user@localhost % surreal start --log trace memory

In order to keep SurrealDB secure, the database disables root-level authentication if a password is not set. To set a root-level authentication login, use the --user and --pass command-line arguments. The following command starts the database with a top-level user named root with a password also set to root.

user@localhost % surreal start --log trace --user root --pass root memory

After running the above command, you should see the SurrealDB server startup successfully.

user@localhost % surreal start --log trace --user root --pass root memory
[2022-07-28 15:50:34] INFO  surrealdb::iam Root authentication is enabled
[2022-07-28 15:50:34] INFO  surrealdb::dbs Database strict mode is disabled
[2022-07-28 15:50:34] INFO  surrealdb::kvs Starting kvs store in memory
[2022-07-28 15:50:34] INFO  surrealdb::kvs Started kvs store in memory
[2022-07-28 15:50:34] INFO  surrealdb::net Starting web server on 0.0.0.0:8000
[2022-07-28 15:50:34] INFO  surrealdb::net Started web server on 0.0.0.0:8000

Starting a multi-node distributed database

For highly-available and highly-scalable setups, SurrealDB can be run on top of a TiKV cluster, with the ability to horizontally scale to 100+ terabytes of data. In this example, we will start a local TiKV cluster with a single node, for development and testing purposes only.

To install TiKV on your development machine, run the following command. This will install the tiup command-line tool, which enables deploying and managing TiKV clusters of any size.

user@localhost % curl -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

Once installed we shall start up a simple single-node development cluster.

user@localhost % tiup playground --tag surrealdb --mode tikv-slim --pd 1 --kv 1
tiup is checking updates for component playground ...
Starting component `playground`: /Users/tobie/.tiup/components/playground/v1.10.2/tiup-playground --tag surrealdb --mode tikv-slim --pd 1 --kv 1
Using the version v6.1.0 for version constraint "".

If you'd like to use a TiDB version other than v6.1.0, cancel and retry with the following arguments:
	Specify version manually:   tiup playground version
	Specify version range:      tiup playground ^5
	The nightly version:        tiup playground nightly

Playground Bootstrapping...
Start pd instance:v6.1.0
Start tikv instance:v6.1.0
PD client endpoints: [127.0.0.1:2379]
To view the Prometheus: http://127.0.0.1:9090
To view the Grafana: http://127.0.0.1:3000

Once TiKV is up and running, we can start a SurrealDB server instance, specifying the TiKV cluster endpoint as the backing data store.

user@localhost % surreal start --log trace --user root --pass root tikv://127.0.0.1:2379
[2022-07-28 15:50:34] INFO  surrealdb::iam Root authentication is enabled
[2022-07-28 15:50:34] INFO  surrealdb::dbs Database strict mode is disabled
[2022-07-28 15:50:34] INFO  surrealdb::kvs Connecting to kvs store at tikv://127.0.0.1:2379
[2022-07-28 15:50:34] INFO  surrealdb::kvs Connected to kvs store at tikv://127.0.0.1:2379
[2022-07-28 15:50:34] INFO  surrealdb::net Starting web server on 0.0.0.0:8000
[2022-07-28 15:50:34] INFO  surrealdb::net Started web server on 0.0.0.0:8000

Next steps

Congratulations, you’ve now successfully started SurrealDB! You are now ready to start inserting data and performing queries against SurrealDB. Take a look at the next chapter to get started with querying SurrealDB.