Skip to content

Docs

Sign In

Multi-tenancy

Namespace & database architecture

SurrealDB scopes data in two levels: a namespace holds one or more databases, and each database holds your tables and other resources. There is no fixed cap on how many namespaces or databases you create. Design is driven by who should be isolated from whom (tenants, environments, product lines) and who is allowed to administer each layer.

In fact, there are some social media platforms that even run by creating an entire database per user.

A more common SaaS pattern is one namespace per tenant so credentials and data never cross tenant boundaries; another pattern is one namespace per environment (dev, staging, prod) with multiple databases inside.

Namespaces are created by root users. Databases live inside a namespace and are created by root or namespace owners/editors once you execute a USE statement to move to that namespace.

Reference pages: DEFINE NAMESPACE, DEFINE DATABASE.

The diagram below shows what each level holds, and three common layouts.

The levels of a SurrealDB server, each inside the one above. The root holds namespaces, root users and access methods, and nodes. A namespace holds databases and namespace users and access methods. A database holds tables, functions, params, analyzers, sequences, users and access methods, buckets, APIs, models and config, and a query runs in one namespace and one database. A table holds records, fields, indexes and events. Three common layouts are a namespace per tenant, each with its own app database; a namespace per environment, such as prod and staging, each holding the same databases; and a database per user inside one namespace.The levels of a SurrealDB server, each inside the one above. The root holds namespaces, root users and access methods, and nodes. A namespace holds databases and namespace users and access methods. A database holds tables, functions, params, analyzers, sequences, users and access methods, buckets, APIs, models and config, and a query runs in one namespace and one database. A table holds records, fields, indexes and events. Three common layouts are a namespace per tenant, each with its own app database; a namespace per environment, such as prod and staging, each holding the same databases; and a database per user inside one namespace.

For convenience, a new running instance will create a new namespace and database that each have the name main. This can be disabled by passing in a flag or setting an environment variable when using the surreal db start command.

Namespaces

Example: create a namespace

Below shows how you can create a namespace using the DEFINE NAMESPACE statement.

DEFINE NAMESPACE platform_ltd;

Databases

A database is where your application schema actually lives. Options such as STRICT control whether CRUD operations may create undefined resources implicitly.

Example: create a database

Below shows how you can create a database using the DEFINE DATABASE statement.

-- Specify the namespace for the database
USE NS platform_ltd;

-- Define database
DEFINE DATABASE app_vitalsense;

Defining a STRICT database

A strict database is one that does not allow a resource to be used unless it has already been defined. The default behaviour in SurrealDB works otherwise, by allowing statements like CREATE, INSERT, and UPSERT to work.

CREATE some_new_table;
INFO FOR DATABASE.tables;

The output of the INFO statement shows that a table called some_new_table has been created with a few default clauses.

{
	some_new_table: 'DEFINE TABLE some_new_table TYPE ANY SCHEMALESS PERMISSIONS NONE'
}

Such an operation within a strict database is simply not allowed.

DEFINE DATABASE new_db STRICT;
USE DATABASE new_db;
CREATE some_new_table;
Output
"The table 'some_new_table' does not exist"

Was this page helpful?

Previous

Schema management

Next

Schema design