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
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
--storedoes not need?ns=; if present it is ignored with a warning. - Namespaces live directly at the root of the store:
file:///var/lib/namidbkeeps namespaceacmein/var/lib/namidb/acme/. Fors3://,gs://andaz://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
| Protocol | How the namespace is chosen |
|---|---|
| HTTP | The path prefix: POST /acme/v0/cypher |
| HTTP | Or the X-NamiDB-Namespace: acme header on the unprefixed /v0/... route |
| HTTP | Neither: --default-namespace (default default) |
| Bolt | The driver’s session database: driver.session(database="acme") |
| Bolt | No database set: --default-namespace |
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:
| Prefixed | Purpose |
|---|---|
GET /:namespace/v0/livez, GET /:namespace/v0/health | Probes (see the warning below) |
POST /:namespace/v0/cypher | Cypher |
POST /:namespace/v0/admin/flush, /admin/compact | Maintenance |
POST /:namespace/v0/admin/backup, /admin/restore | Backup and restore |
GET /:namespace/v0/admin/restore-points | The namespace’s restore point window (does not open a cold namespace) |
GET /:namespace/v0/admin/queries, POST …/admin/queries/:id/cancel | In-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:
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
| Setting | Default | Meaning |
|---|---|---|
--max-namespaces | 100 | Namespaces open at once. At the cap, idle ones are evicted oldest-first. 0 = unlimited. |
--namespace-idle-timeout | 1h | How long a namespace must be unused before it may be evicted. |
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE | 0 (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:
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®ion=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®ion=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/healthopens the namespace it asks about, and the unprefixed/v0/healthopens the header or default namespace. UseGET /v0/livezfor node liveness; it opens nothing. --fence-policy. The defaultstealmakes a fenced writer reopen and take the namespace back, which suits a single server. When something outside decides ownership, run every server withyield: 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.