SurrealDB: one binary that runs five ways, and a workspace with two side projects in it

Five deployment shapes come out of the same single binary

The paragraph explaining what the project is ends with the sentence that matters most for an evaluation: given that it is a single Rust binary, SurrealDB can run embedded in an application, in the browser through WebAssembly, at the edge, self-hosted as a single backend node, or in a distributed cluster in the cloud.

Five shapes, one artefact. That is an unusual property for a database and it changes what you are committing to. An embedded deployment is a library dependency with the database's storage on your disk, and there is no server to secure because there is no server. A distributed deployment is the same binary with a cluster topology, and the operational work is entirely different.

The readme also describes it as usable as a backend-as-a-service given its support for end user authentication, and lists a realtime API layer with security permissions built in among the features. So the pitch is not a database plus a separate application server; it is one process that does both, and can be either a library you link or a service you run.

Which of those five you pick determines almost everything else about the deployment, so it is the first decision rather than the last one.

Multi-model means one engine, not one table type

The word doing the work in the description is multi-model, and the project spells out what it covers: document, graph, relational, time-series, geospatial and key-value data types, with search and retrieval across full-text, vector and hybrid, plus real-time and event-driven capabilities.

The features list adds the specifics. Multi-row, multi-table transactions with ACID. Record links and directed typed graph connections. Structured and unstructured data stored together. Incrementally computed views for pre-computed analytics. Realtime API layer with permissions in the product. Embedded JavaScript functions for custom functionality. And a Model Context Protocol server for language model and agent integration.

The relational entry is specified with a parenthetical that reads oddly until you parse it: relational, enforcing schema and schemaless. That is a claim that both modes exist in the same engine rather than a contradiction, and it is the kind of thing worth testing against your own data model before you commit.

The access control row is the one an engineer should stop on. Granular access control described as row-level permissions-based, which means the database can authorise a read or a write per record rather than per table, and a realtime layer whose subscriptions inherit that.

One query language, several ways to reach it

Querying is where a multi-model engine has to prove itself, and the answer is a language called SurrealQL, described as an SQL-like intuitive query language offered natively.

Around it the readme lists the access paths. SQL querying from client devices, GraphQL, transactions, WebSocket connections, structured and unstructured data, graph querying, full-text and vector indexing, and geospatial querying. Client SDKs are linked for Rust and for JavaScript, with separate links for browser and client-device paths.

There is also a contents section whose headings describe the model rather than the API. One heading says advanced inter-document relations and analysis, no joins, no pain, which is a claim about how relationships are traversed rather than about SQL compatibility. Another says realtime live queries and data changes direct to application, which is the subscription layer described as sending changes to the application rather than being polled.

So the practical question for an evaluator is not whether SurrealDB speaks SQL. It is whether your access patterns are join-shaped or traversal-shaped, because the readme is claiming the second and treating the first as something you can avoid rather than something you must write.

The workspace version is a nightly string on the main branch

The root manifest is where the release state shows, and it is worth reading before the release list.

The workspace version is a nightly string built from the same three-part number as the newest release, which is what a main branch looks like between releases. The root package is marked as not publishable, and the workspace itself uses the newest resolver generation and the current edition.

The internal crates carry the same nightly string in their dependency declarations, with the path and a default-features flag on most of them and a local path in the workspace dependency table. So a downstream crate that depends on the published library will resolve the published version, while anyone building from this branch is building the nightly line whether or not they meant to.

The release list also shows two major lines being cut close together, with a stable release, a release from the previous major line, and a beta of the newest, all published on the same day. Whatever the project's versioning policy, that pattern means the tag you pick determines which line you get, so read the release notes for the line rather than assuming the newest tag is the safest choice.

Two side projects are built in the same workspace as the database

The workspace members are not all database crates, and that is the detail a reader will notice first.

There is the root package, then a group of crates under the main database directory, covering the abstract syntax tree, collections, shared common types, the core engine, a Model Context Protocol crate, the parser, the server, a strand type, a token type, and types with their derive macros. Then two groups with their own names: one is a single crate for a machine learning component, and the other is five crates for a runtime and its macros, types and a demo.

The readme does not describe either project. What it does mention is the Model Context Protocol server for agent integration, and one of the language tests directory at the root suggests those query languages are tested as a suite rather than a single parser.

For an adopter the consequence is practical. The repository you clone to build the database also builds two other things, and a contributor reading the workspace file has to work out which crates belong to the product they are evaluating. Nothing is hidden, but nothing is separated either.

The Makefile is a shim that requires another build tool to be installed

The build entry point is short enough to read in full, and it explains the tooling requirement.

The default goal depends on a dependency check, and the default recipe runs a task tool. There is a rule that ignores the makefile as a target, and a catch-all pattern rule that passes any target through to the same task tool after the dependency check. The check itself runs the task tool's help output, and if that fails it prints an error saying the tool must be installed, followed by the exact install command with flags to skip default features, force the install and use the lock file, and a link.

So the answer to how you build this is that you install a task runner for a build system, and then the makefile is a convenience layer. That is a defensible choice for a project with a large build matrix, and it is one more tool in the chain for a first-time contributor.

The rest of the root is the apparatus of a large Rust project: a nightly toolchain file and a stable one, formatting and linting configuration, a dependency policy file, fuzzing, profiling, supply-chain, packaging, shell and Nix entry points, a changelog generator configuration, a context file for documentation tooling, a revision lock, a review document, and a separate makefile for continuous integration and one for local use.

The documentation is a site, a course and an interactive book

The documentation section is three links and one of them is unusual.

There is the documentation site for installation, development, deployment and administration. There is a university, described as guidance in course form. And there is an interactive book with a name and an author, linked separately from the university.

The getting started section is correspondingly thin. It says starting is as easy as starting the database server, choosing your platform and integrating an SDK, and it points at platform tutorials rather than giving a first command. The client links fan out to server-side integrations for Rust and JavaScript, then to engine documentation for the browser and client-device paths.

That combination tells you something about the audience. A database whose audience needs an interactive book and a course is a database with a lot of conceptual surface rather than a small operational one, and the getting-started section is deliberately not a tutorial. Plan to budget reading time rather than expect a five minute path, and use the university if you are onboarding more than one person.

Editorial conclusion

Use SurrealDB if you want document, graph and relational modelling in one engine, you want a realtime API layer with permissions rather than a separate application server, and you want the option to embed the database in your own process instead of operating a service. Do not adopt it on the strength of the feature list alone, because the version scheme carries a nightly suffix on the main branch and a major version was cut while the two earlier lines were still being released. Before you start: read the release notes for the line you are pinning rather than the newest tag, and check whether the two side projects in the workspace are something you need, because they are built in the same tree and their crates are workspace members alongside the database itself.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes