Starting 
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.