File-backed

A single node of SurrealDB can be run with data persisted to the filesystem, using SurrealKV (surrealkv://) as the storage engine. It uses the same transaction and isolation semantics as every other SurrealDB deployment.

Start the server

surreal db start surrealkv://mydatabase.db

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.

surreal db start --log debug surrealkv://mydatabase.db

The SurrealDB server runs with authentication enabled by default. To disable it, the --unauthenticated flag can be passed in.

surreal db start --unauthenticated surrealkv://mydatabase.db

However, for anything but simple testing, it is better to 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 set to secret. 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 db start --user root --pass secret surrealkv://mydatabase.db

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 db start --user root --pass secret --bind 0.0.0.0:8080 surrealkv://mydatabase.db

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

INFO surrealdb::core::kvs::ds: Starting kvs store at relative path surrealkv://mydatabase.db
INFO surrealdb::core::kvs::ds: Started surrealkv kvs store
INFO surrealdb::core::kvs::ds: This is a new SurrealDB instance. Initialising default namespace 'main' and database 'main'
INFO surrealdb::core::kvs::ds: Credentials were provided, and no root users were found. The root user 'root' will be created
INFO surrealdb::net: Started web server on 0.0.0.0:8080

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

SurrealKV

SurrealKV is an embedded storage engine developed in house by SurrealDB: a versioned key-value store built on an LSM (log-structured merge) tree, with optional time-travel reads when versioning is enabled in SurrealDB. It is implemented in Rust and ships with the main SurrealDB release so the storage layer can evolve with SurrealDB’s access patterns.

From SurrealDB 4.0, SurrealDB uses SurrealKV 1.0, which converts a data directory written by RocksDB or by an earlier SurrealKV release the first time it opens it. The conversion is one-way, so take a copy of the directory first, or convert ahead of time into a new directory with skv migrate, which leaves the original unchanged. See Moving a RocksDB database to SurrealKV and Converting ahead of time with skv. Before 4.0, SurrealKV was in beta.

Key features

At a high level, SurrealKV provides:

• •

  MVCC-backed concurrent reads and writes on disk (isolation semantics are defined by the query layer, not by the engine alone).

• •

  Durability options (immediate vs eventual flush semantics) aligned with how you configure sync behaviour.

• •

  Built-in versioning for historical / temporal queries in SurrealDB when you opt in. See versioned startup and the VERSION clause for details.

• •

  LSM structure: writes batch into memtables and flush to SSTables.

• •

  Value log (WiscKey-style): Allows large values to be stored separately with garbage collection.

• •

  Checkpoint and restore support in the engine for consistent snapshots (see upstream SurrealKV documentation).

Parameters on startup

Parameters such as versioned and sync control versioning and durability. See Supported parameters for SurrealKV and SurrealKV environment variables.

SurrealKV performance characteristics and trade-offs

Strengths

• •

  Sequential write path: LSM trees batch writes and flush to sorted runs, which maps well to SSDs and sequential I/O.

• •

  Concurrent reads: MVCC snapshots let readers proceed without blocking writers in the common case.

• •

  Scalability: Unlike SurrealKV's earlier designs, the LSM architecture is intended to support datasets larger than RAM by keeping the hot working set in memtables and caching while spilling cold data to SSTables on disk.

Limitations and operational notes

• •

  Compaction and space: Compaction reclaims space but uses extra I/O and temporary disk headroom while merges run.

• •

  Read amplification: Point lookups may touch several levels; very wide range scans can require more I/O than a single B-tree-style read, so plan indexes and query shapes accordingly.

• •

  Platform notes: The SurrealKV library targets Unix-like desktop and server OSes; in the browser, the same engine keeps its files in the Origin Private File System and runs in a dedicated worker (see the Wasm engine). Windows support exists with some filesystem caveats. See upstream platform compatibility notes for more details.

Performance implications

SurrealKV tends to work well for write-heavy workloads, prefix-based access patterns, and time-series or versioned data where append-heavy writes and ordered keys are common. Point lookups are typically efficient, though they may involve checking multiple levels of on-disk data structures. Large range scans can require reading across multiple SSTables and levels, which may increase I/O without careful compaction and schema design. As with most LSM-based systems, performance can degrade in severely memory- or disk-constrained environments without tuning.

Run your first query

With the server running, open a second terminal and connect to it with the surreal db sql command. This starts a SurrealQL REPL against the server, using the credentials from the step above.

surreal db sql --endpoint http://localhost:8000 --username root --password secret --namespace main --database main --pretty

Create a record. There is no need to define the table first, because SurrealDB creates it on the first write.

CREATE person:tobie SET name = "Tobie", city = "London";

[
	{
		city: 'London',
		id: person:tobie,
		name: 'Tobie'
	}
]

Select it back to confirm the round trip.

SELECT name, city FROM person;

[
	{
		city: 'London',
		name: 'Tobie'
	}
]

When you finish, exit the REPL with Ctrl+C. The record persists on disk, so it is still there the next time you start the server against the same path.

Next steps

• •

  Query from your application with an SDK - each language guide starts with a connect-and-query walkthrough.

• •

  Try SurrealQL without a server in the Studio Sandbox.

• •

  Learn the query language, starting with the SELECT statement.