Run a multi-node, scalable cluster with TiKV

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 tikv://127.0.0.1:2379

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

user@localhost % surreal start --log trace tikv://127.0.0.1:2379

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 tikv://127.0.0.1:2379

In order to change the default port that SurrealDB uses for web connections and from database clients you can use the --bind argument. The following command starts the database on port 8080.

user@localhost % surreal start --log trace --user root --pass root --bind 0.0.0.0:8080 tikv://placement.driver.hostname.or.ip:2379

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

user@localhost % surreal start --log trace --user root --pass root --bind 0.0.0.0:8080 tikv://127.0.0.1:2379
[2023-04-03 08:45:42] INFO  surrealdb::iam Root authentication is enabled
[2023-04-03 08:45:42] INFO  surrealdb::iam Root username is 'root'
[2023-04-03 08:45:42] INFO  surrealdb::dbs Database strict mode is disabled
[2023-04-03 08:45:42] INFO  surrealdb::kvs Connecting to kvs store at tikv://127.0.0.1:2379
[2023-04-03 08:45:42] INFO  surrealdb::kvs Connected to kvs store at tikv://127.0.0.1:2379
[2023-04-03 08:45:42] INFO  surrealdb::net Starting web server on 0.0.0.0:8080
[2023-04-03 08:45:42] INFO  surrealdb::net Started web server on 0.0.0.0:8080

For details on the start command, and all of the available configuration options and arguments, view the start command documentation.