Skip to content

Docs

Sign In

Overview

Architecture

This page explains the two topologies an instance can run on, and what each one means for growth and recovery.

The plan you choose when you create an instance selects the topology.

Instances build on the layered architecture of SurrealDB, which separates storage from compute. That separation lets an instance grow, replicate, and recover without you sharding or resharding the database yourself.

Start: single node

The Start plan provides one compute node backed by a dedicated disk. Compute and storage are sized together and resized together, and the node holds the only copy of the working data.

Diagram of the single-node topology: one SurrealDB compute node paired with its own dedicated disk-based storage volume.Diagram of the single-node topology: one SurrealDB compute node paired with its own dedicated disk-based storage volume.

This topology suits development, staging, and production workloads that fit on one node and can tolerate a short recovery window. It scales vertically: as load grows, you move to a larger instance type. See Scaling.

Because there is a single node, there is no failover inside the instance. Backups are the recovery mechanism. See High availability for what that means in practice.

Scale: multi-node cluster

The Scale plan runs a cluster of three compute nodes or more. Each node runs in a different availability zone within the region, with its own disk for the commit log, and the data itself is kept in object storage.

Diagram of the multi-node topology: three SurrealDB compute nodes, each in its own availability zone and backed by its own storage disk, split into a compute layer and a storage layer.Diagram of the multi-node topology: three SurrealDB compute nodes, each in its own availability zone and backed by its own storage disk, split into a compute layer and a storage layer.

Every node accepts queries and runs transactions, so a query does not need to know which node holds which data. Writes are ordered by one node, the sequencer, and copied to a node in another zone, the acker. A commit is acknowledged only after both have written it to their own disk, so every acknowledged write exists in two availability zones. The data is written to object storage after that, outside the commit path.

The practical consequences are:

  • Node loss is survivable. If the node holding the sequencer or the acker role fails, another node takes the role over, and writes pause briefly while it does. See High availability.

  • Three nodes are the minimum. Two nodes hold the sequencer and acker roles, and the third lets the cluster lose a node and still keep two copies of every write.

  • Read capacity scales horizontally. Adding nodes adds capacity for queries. Every write passes through the sequencer, so write throughput grows with a larger node size rather than with more nodes.

  • Self-hosting the same topology is more work. Running it yourself means operating Kubernetes, storage replication, patching, backups, and upgrade orchestration. Scale covers that work for you. Compare Self-hosted deployment models.

Note

Several Scale capabilities are still on the roadmap: cross-region replication, automatic sharding, and read replicas. See Pricing and Changelog for current availability.

Related pages

Was this page helpful?

Previous

SurrealDB Earth

Next

Scaling