Deployment

SurrealDB separates the query engine (compute) from the underlying storage layer. The same SurrealQL, APIs, and client SDKs work across embedded devices, single-node servers, distributed clusters, and SurrealDB Cloud — so you can change how the database runs without rewriting application code.

This page explains the available deployment options, storage engines, and how to choose the right architecture for your workload. For how the compute and storage layers interact, see Architecture.

Deployment models summary

Architecture overview

SurrealDB consists of two major layers:

Query layer

• Parses and executes SurrealQL

• Authenticates connections and sessions

• Enforces table- and field-level permissions on reads and writes

• Plans index-backed queries, maintains index entries during writes, and coordinates transactions

Storage layer

• Handles persistence and durability

• Determines scalability, temporal versioning, replication, and fault tolerance

Because these layers are separated in the architecture, applications can move between deployment models without changing application code or queries. Embedded and browser deployments still use both layers, but they run in-process rather than as separate services.

SurrealDB Cloud

SurrealDB Cloud provides a fully managed deployment platform built on scalable, fault-tolerant infrastructure. It removes the operational complexity of running clusters while providing production-ready deployments.

For more detail, see What is SurrealDB Cloud? and Cloud architecture.

Features

• Managed SurrealDB infrastructure

• Automatic scaling

• High availability

• Managed backups

• Secure connectivity

• Multi-node distributed architecture (Dedicated tiers)

• Production monitoring and operations

Best for

• Managed infrastructure

• Rapid production deployment

• Scaling applications

• SaaS platforms

• Enterprise workloads

Benefits compared to self-hosting

Single-node (RocksDB)

Single-node deployments run SurrealDB as a standalone server process using RocksDB. This is the simplest and most widely used production architecture on disk. RocksDB is a high-performance LSM-tree key-value store optimised for high write throughput, SSD storage, and predictable persistence.

Best for

• Small to medium production workloads

• Internal tooling

• Development environments

• Applications without horizontal scaling or built-in cluster fault tolerance

Limitations

• Vertical scaling only

• No built-in distributed fault tolerance

For setup examples, see Run a single-node, on-disk server.

Common deployment methods

CLI

surreal start rocksdb://path/to/database

Docker

docker run --rm \
  -p 8000:8000 \
  surrealdb/surrealdb:latest \
  start --user root --pass secret rocksdb://data/database.db

See also Self-hosted deployment for Docker, Kubernetes, and platform guides.

SurrealKV (beta)

For single-node and embedded workloads, SurrealKV is SurrealDB’s own LSM-backed storage engine, developed in concert with the database rather than as a third-party dependency. That co-development shows up in day-to-day operation: SurrealKV exposes a comparatively small configuration surface and environment variable set next to RocksDB’s extensive tuning knobs.

SurrealKV remains beta. For production on disk today, prefer RocksDB unless you are deliberately evaluating SurrealKV. It is nonetheless a serious storage path inside the project: features such as temporal reads via the VERSION clause were exercised on SurrealKV first and have since been extended to SurrealMX and RocksDB where the engine supports them.

To try SurrealKV on a server, see the SurrealKV tab on Run a single-node, on-disk server and the surreal start storage parameters.

Multi-node SurrealDS (coming soon)

For high availability and horizontal scalability,

In distributed deployments:

• Multiple SurrealDB query nodes can scale horizontally against shared storage

• The primary dataset lives in SurrealDS rather than on individual query nodes

• SurrealDS manages replication, consensus, fault tolerance, and distributed transactions

This architecture supports zero-downtime scaling, resilient clusters, high-throughput workloads, geographically distributed applications, and operational patterns such as branching and fast recovery. Object-storage backing for tiered data is on the product roadmap.

When SurrealDS is available, operational signals will be documented under Enterprise observability (including the surrealdb.ds.* metric family).

Features

Horizontal scalability — Scale query and storage nodes independently.

Fault tolerance — Replication and consensus allow clusters to tolerate node failures.

Distributed ACID transactions — Strong transactional guarantees across distributed infrastructure.

Large-scale storage — Designed for very large datasets and high-concurrency production workloads.

Best for

• Enterprise deployments

• High-availability applications

• Multi-region systems

• Large graph workloads

• Real-time platforms

• AI-native distributed systems

Operational considerations

Distributed deployments add cluster orchestration, node management, monitoring, and replication management. Teams that want distributed scalability without operating that stack should consider SurrealDB Cloud.

Embedded deployments

Embedded deployments run SurrealDB inside your application process without a separate database server. The query and storage layers share the process (and, in the browser, the same runtime), which removes network latency between your app and the database. This model suits edge computing, mobile and desktop software, offline-first apps, browser PWAs, and AI workflows that need minimal latency.

For language-specific setup, see Embedding SurrealDB and Storage engines.

Supported runtimes

SurrealDB supports embedded operation in Rust, Go, JavaScript / TypeScript, WebAssembly, Python, and .NET. Capabilities vary by SDK and storage backend — check the embedding guide for your language.

Storage options

In-memory (SurrealMX) — Default in-memory backend since SurrealDB 3.0, with optional snapshots or append-only persistence and support for versioned queries. See Run a single-node, in-memory server.

RocksDB — Persistent embedded storage for write-heavy, SSD-backed workloads. See File-backed storage.

SurrealKV — Same beta engine as single-node server deployments; useful when you want SurrealDB’s native LSM path in-process. Prefer RocksDB for production embedded disk unless you are evaluating SurrealKV deliberately.

IndexedDB (browser) — Browser-native persistence with binary serialisation for PWAs and local-first web apps. See Embedding SurrealDB and the Wasm engine.

Choosing the right deployment model

Use SurrealDB Cloud when

• You want managed infrastructure

• You need production-ready HA quickly

• Your team prefers building applications over operating databases

Use single-node deployments with RocksDB when

• Simplicity matters most

• Scaling requirements are moderate

• You run small-to-medium production workloads without cluster-level fault tolerance

Use multi-node with SurrealDS when (

• High availability is required

• Workloads need horizontal scaling

• Infrastructure spans multiple nodes or availability zones

Until SurrealDS is available, use SurrealDB Cloud Dedicated tiers or contact SurrealDB for Enterprise early-access programmes.

Use embedded deployments when

• You run on edge devices or in the browser

• Offline operation is required

• Minimising latency between app and database is critical

Conclusion

SurrealDB’s architecture lets the same engine and query language run across embedded, single-node, distributed, and managed models. Whether you embed SurrealDB in a browser, run RocksDB on one server, plan for SurrealDS when it ships, or use SurrealDB Cloud today, you can match operational and scalability requirements without rewriting queries.

Next steps

SurrealDB Cloud

Provision a managed SurrealDB instance with built-in monitoring, network access controls and operations tooling.

Self-hosted

Run SurrealDB on Docker, Kubernetes (AKS, EKS, GKE) or as a standalone binary with full control over storage and configuration.

Observability

Metrics, OTLP and Prometheus access, audit logs and slow-query logs for both Community and Enterprise editions.