SurrealDB Namespaces As Auth Boundaries For Multi-Tenant Isolation

Problem: Isolating Tenants Without Duplicate Clusters

SurrealDB's two-tier model uses namespaces as authentication and authorization boundaries, and databases as logical data partitions inside those boundaries. Applications that treat databases as standalone isolation units often hit permission leaks and unexpected real-time event scope.

How Namespaces and Databases Work

A namespace defines who can authenticate and what roles they hold. Databases inside a namespace share real-time event subscriptions unless the namespace is explicitly qualified. SurrealQL resolves table references by checking the active namespace, set via USE NAMESPACE name DATABASE name or qualified as namespace::database::table.

Worked Example: Creating Two Tenant Boundaries

CREATE NAMESPACE tenant_a AUTH { TYPE PASSWORD, PASS 'strong_password_a' };

CREATE NAMESPACE tenant_b AUTH { TYPE PASSWORD, PASS 'strong_password_b' };

USE NAMESPACE tenant_a; CREATE DATABASE prod;

USE NAMESPACE tenant_b; CREATE DATABASE prod;

SELECT NAMESPACE(); SELECT DATABASE();

Expected checks: SELECT NAMESPACE() returns the last USE context. A session authenticated as tenant_a cannot query tenant_b tables without switching namespace and re-authenticating. Cross-namespace table references require explicit qualification, and real-time subscriptions remain namespace-scoped.

Trade-off: No Native Cross-Namespace Joins

SurrealQL does not support joining tables across namespaces. Aggregation across tenants must happen at the application layer or through manually managed cross-database subscriptions. Creating excessive namespaces increases metadata overhead in the server's routing tables, and permission mapping per namespace can become operationally complex.

Actionable Closing

Map security domains to namespaces and environments to databases. Verify isolation by opening two sessions, authenticating to each namespace, and confirming SELECT NAMESPACE() and query results differ. Keep namespace count intentional and document which subscriptions are namespace-wide.