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.