Skip to content

Multi-tenant mode

By default namidb-server serves the single namespace named in --store. With --multi-tenant it serves any number of namespaces from one process. Each namespace is a separate graph with its own manifest, WAL, data files, writer, indexes and statistics, so tenants are physically isolated, and tokens can be scoped to the namespaces they may reach.

Start it

Terminal window
namidb-server \
--multi-tenant \
--store "file:///var/lib/namidb" \
--auth-tokens-file /etc/namidb/tokens.json \
--bolt-listen 0.0.0.0:7687
  • In multi-tenant mode --store does not need ?ns=; if present it is ignored with a warning.
  • Namespaces live directly at the root of the store: file:///var/lib/namidb keeps namespace acme in /var/lib/namidb/acme/. For s3://, gs:// and az:// they live at the root of the bucket or container; a path prefix in the URI is not used.
  • A namespace is created the first time a request opens it.

Route a request to a namespace

ProtocolHow the namespace is chosen
HTTPThe path prefix: POST /acme/v0/cypher
HTTPOr the X-NamiDB-Namespace: acme header on the unprefixed /v0/... route
HTTPNeither: --default-namespace (default default)
BoltThe driver’s session database: driver.session(database="acme")
BoltNo database set: --default-namespace
Terminal window
curl -s localhost:8080/acme/v0/cypher \
-H "Authorization: Bearer $ACME_TOKEN" -H 'Content-Type: application/json' \
-d '{"query": "CREATE (:Item {sku: \"A-1\"})"}'
curl -s localhost:8080/v0/cypher \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'X-NamiDB-Namespace: acme' \
-H 'Content-Type: application/json' \
-d '{"query": "MATCH (i:Item) RETURN i.sku AS sku"}'
# {"columns":["sku"],"rows":[{"sku":"A-1"}]}
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("namidb", ACME_TOKEN))
with driver.session(database="acme") as s:
print(s.run("MATCH (i:Item) RETURN i.sku AS sku").value()) # ['A-1']

An explicit Bolt transaction is pinned to the database named when it began.

Every per-namespace route has a prefixed form and an unprefixed form that resolves the header or default namespace:

PrefixedPurpose
GET /:namespace/v0/livez, GET /:namespace/v0/healthProbes (see the warning below)
POST /:namespace/v0/cypherCypher
POST /:namespace/v0/admin/flush, /admin/compactMaintenance
POST /:namespace/v0/admin/backup, /admin/restoreBackup and restore
GET /:namespace/v0/admin/restore-pointsThe namespace’s restore point window (does not open a cold namespace)
GET /:namespace/v0/admin/queries, POST …/admin/queries/:id/cancelIn-flight queries, scoped to the namespace

GET /v0/version and GET /v0/metrics are process-wide and take no prefix.

Scope tokens to namespaces

In a tokens file, a namespaces list restricts a token. Omit it for a token that reaches every namespace; an empty list ([]) denies all of them.

{
"tokens": [
{ "name": "admin", "token": "…", "role": "read-write" },
{ "name": "acme-app", "token": "…", "role": "read-write", "namespaces": ["acme"] },
{ "name": "dashboard", "token": "…", "role": "read-only" }
]
}

The scope is enforced on every HTTP route and, for Bolt, on every statement:

Terminal window
curl -s localhost:8080/globex/v0/cypher -H "Authorization: Bearer $ACME_TOKEN" \
-H 'Content-Type: application/json' -d '{"query": "RETURN 1 AS x"}'
# 401 {"error":"missing or invalid bearer token, or token not scoped to this namespace"}

Over Bolt the same request fails with Neo.ClientError.Security.Forbidden. JWTs are scoped the same way through --jwt-namespaces-claim. Details and hot reload: Authentication.

Namespace names

Names match [a-z0-9][a-z0-9_-]{0,62}: lowercase letters, digits, - and _, 1 to 63 characters, not starting with _ or -. Check one with namidb namespace-check <name>. A request for an invalid name is refused before anything is opened.

Capacity and eviction

SettingDefaultMeaning
--max-namespaces100Namespaces open at once. At the cap, idle ones are evicted oldest-first. 0 = unlimited.
--namespace-idle-timeout1hHow long a namespace must be unused before it may be evicted.
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE0 (off)Per-namespace read cap inside the process-wide read gate, so one tenant cannot take every slot.

Eviction drops the in-memory session, not the data; the next request reopens the namespace. A namespace with a read in flight is never idle. Caches are process-wide with one aggregate budget, so many tenants do not multiply memory use; see Memory and caches. Namespaces open independently, so a slow cold open (a long WAL to replay) only delays requests for that namespace.

Restore into a new namespace

A multi-tenant server can restore a backup into a namespace that does not exist yet, through its own store. Both backup and restore need --backup-target-uri, which limits where they may copy:

Terminal window
namidb-server --multi-tenant --store "s3://graphs?region=us-east-1" \
--backup-target-uri "s3://graph-backups/namidb?region=us-east-1" …
# Online backup of acme:
curl -s -X POST localhost:8080/acme/v0/admin/backup \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"to": "s3://graph-backups/namidb/acme-nightly?ns=acme&region=us-east-1"}'
# {"bytes_copied":649,"objects_copied":4,"source_version":1}
# Restore it as a new namespace acme-restored:
curl -s -X POST localhost:8080/acme-restored/v0/admin/restore \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"from": "s3://graph-backups/namidb/acme-nightly?ns=acme&region=us-east-1", "verify": true}'
# {"bytes_copied":658,"objects_copied":4,"source_version":0}

A restore refuses (409) a target that is open, being opened, already being restored, or already has data. The full rules are in Backup and restore.

One owner per namespace

A namespace has exactly one writer, fenced by an epoch in its manifest. Any process that opens it for writing claims the next epoch and fences the previous one: a second server, an old instance overlapping a new one during a rolling deploy, or an embedded Python client on the same bucket. Two writers never add throughput; they fence each other.

  • Route each namespace to one server. If you run several servers on the same store, the layer in front must send all traffic for a namespace, health probes included, to its owner.
  • Probes open namespaces. GET /:namespace/v0/health opens the namespace it asks about, and the unprefixed /v0/health opens the header or default namespace. Use GET /v0/livez for node liveness; it opens nothing.
  • --fence-policy. The default steal makes a fenced writer reopen and take the namespace back, which suits a single server. When something outside decides ownership, run every server with yield: a fenced writer then stops writing and reports itself degraded (readiness 503) until the process, or the namespace, is opened again.

Many tenants in one namespace instead

The alternative is a single namespace with a tenant_id property on every node. It is cheaper to run but isolation is only logical: every query must filter by tenant, and all tenants share one vector index per (label, property), so a vector search must carry the tenant in its filter (see Search). Treat it as a convenience, not a security boundary; use multi-tenant mode when tenants must not see each other.