# Multi-node

Run SurrealDB against distributed storage for horizontally scalable, highly available clusters.

Multi-node SurrealDB requires **shared distributed storage** - a backend that every query node can reach with transactional consistency. A single RocksDB file on one server (or one Kubernetes pod) is **not** a multi-node cluster; it is the [single-node, on-disk](/docs/running/file-backed.md) model.

For managed production clusters, see the [Scale](https://surrealdb.com/pricing/scale) plan on [managed instances](/docs/manage/instances.md), which runs on distributed storage with replication and consensus. For self-hosted multi-node clusters on Kubernetes, use [SurrealDB Enterprise](https://surrealdb.com/enterprise); see also the [Managed Kubernetes](/docs/manage/self-hosted/managed-kubernetes.md) option page for Amazon EKS, Google GKE, and Azure AKS.

> [!IMPORTANT]
> The section below uses **TiKV** only as a local open-source playground for experimenting with multi-node connectivity. It is **not** the storage engine behind Cloud Scale or Enterprise deployments, and it is not recommended for production HA.

## Local development

The following starts a local distributed-storage playground for development, then connects SurrealDB to it.

```bash
curl -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
tiup playground --tag surrealdb --mode tikv-slim --pd 1 --kv 1
```

Start SurrealDB against the playground endpoint:

```bash
surreal start tikv://127.0.0.1:2379
```

The default logging level for the database server is `info`. 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.

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

Configure your initial root-level user with `--user` and `--pass`. The root user is persisted in storage, so you do not need those flags on subsequent starts.

```bash
surreal start --user root --pass secret tikv://127.0.0.1:2379
```

Change the listen port with `--bind`:

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

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

```text
surreal start --user root --pass secret --bind 0.0.0.0:8080 tikv://127.0.0.1:2379
```
```text title="Output"
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.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](/docs/reference/cli/surrealdb-cli/overview.md).

## Environment variables

Environment variables such as `SURREAL_TIKV_REQUEST_TIMEOUT` can be set to modify distributed-storage client behaviour. See [distributed storage environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md#tikv-environment-variables).