Run a multi-node, scalable cluster

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.

curl -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

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

tiup playground --tag surrealdb --mode tikv-slim --pd 1 --kv 1

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

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 debug level logging, resulting in more logs being output to the terminal. If extra verbosity is not needed, specify a lower level or simply remove the flag, which will default to the info level.

surreal start --log debug tikv://127.0.0.1:2379

In order to keep SurrealDB secure, configure your initial root-level user by setting 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. The root user will be persisted in storage, which means you don’t have to include the command line arguments next time you start SurrealDB.

surreal start --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.

surreal start --user root --pass root --bind 0.0.0.0:8080 tikv://127.0.0.1:2379

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

surreal start --user root --pass root --bind 0.0.0.0:8080 tikv://127.0.0.1:2379
2025-02-14T12:16:28.660617Z  INFO surreal::env: Running 2.2.0 for macos on aarch64
2025-02-14T12:16:28.660678Z  INFO surrealdb::core::kvs::ds: Connecting to kvs store at tikv://127.0.0.1:2379
2025-02-14T12:16:28.660825Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.661224Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.662509Z  INFO tikv_client::pd::cluster: All PD endpoints are consistent: ["127.0.0.1:2379"]
2025-02-14T12:16:28.662547Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.662756Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.663523Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.663710Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:2379"
2025-02-14T12:16:28.664321Z  INFO surrealdb::core::kvs::ds: Connected to kvs store at tikv://127.0.0.1:2379
2025-02-14T12:16:28.665553Z  INFO tikv_client::pd::client: connect to tikv endpoint: "127.0.0.1:20160"
2025-02-14T12:16:28.665568Z  INFO tikv_client::common::security: connect to rpc server at endpoint: "http://127.0.0.1:20160"
2025-02-14T12:16:28.667826Z  WARN surrealdb::core::kvs::ds: Credentials were provided, but existing root users were found. The root user 'root' will not be created
2025-02-14T12:16:28.667832Z  WARN surrealdb::core::kvs::ds: Consider removing the --user and --pass arguments from the server start command
2025-02-14T12:16:28.680059Z  INFO surrealdb::net: Listening for a system shutdown signal.
2025-02-14T12:16:28.680066Z  INFO surrealdb::net: Started web server on 0.0.0.0:8080

For details on the different commands available, visit the CLI tool documentation.