Skip to content

HTTP server

namidb-server serves one namespace (or, with --multi-tenant, many) over an HTTP JSON API, and optionally over Bolt for Neo4j drivers. It is the same engine as the embedded library; the server adds authentication, background maintenance, admission control, metrics and admin endpoints.

Start it

Terminal window
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
namidb-server \
--store "file:///var/lib/namidb?ns=prod" \
--listen 0.0.0.0:8080 \
--bolt-listen 0.0.0.0:7687

Or with the official image (see Install):

Terminal window
docker run -d --name namidb -p 8080:8080 -p 7687:7687 \
-v namidb-data:/var/lib/namidb \
-e NAMIDB_AUTH_TOKEN \
-e NAMIDB_BOLT_LISTEN=0.0.0.0:7687 \
namidb/namidb-server:3.3.0 --store "file:///var/lib/namidb?ns=prod"

Every flag also reads an environment variable (--store ↔ NAMIDB_STORE, --listen ↔ NAMIDB_LISTEN, …); a flag on the command line wins over the variable. The complete list is in the configuration reference.

Check it is up:

Terminal window
curl -s localhost:8080/v0/health
# {"status":"ok","namespace":"prod","manifest_version":0,"epoch":0,"writer":"ok","memtable_bytes":0,...}
curl -s localhost:8080/v0/cypher \
-H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"query": "RETURN 1 + 41 AS n"}'
# {"columns":["n"],"rows":[{"n":42}]}

Authentication is required

Since 2.2.0 the server refuses to start without an auth source:

Error: no auth configured: set --auth-token / NAMIDB_AUTH_TOKEN or --auth-tokens-file,
or pass --no-auth / NAMIDB_NO_AUTH=1 to run without auth on purpose

Pick one:

OptionUse it for
--auth-token / NAMIDB_AUTH_TOKENOne read-write bearer token.
--auth-tokens-fileSeveral named tokens, read-only roles, namespace scopes, hot reload.
--jwt-jwks-url and friendsOIDC / JWT bearer tokens (build with the jwt feature).
--no-authLocal development only: every request is anonymous read-write.

The health, liveness, version and metrics endpoints are always public. Details: Authentication.

What runs in the background

TaskDefaultFlag
Flush the in-memory table to level-0 data filesevery 30s, and as soon as it holds 64 MiB--flush-interval, --memtable-flush-bytes
Compact level-0 files and sweep unreachable objectsevery 300s, and as soon as a bucket holds 8 L0 files--compaction-interval, --compaction-l0-trigger
Delete objects no live manifest referencesduring the sweep, only when older than 24h--sweep-min-age, --sweep-delete
Reload --auth-tokens-fileevery 10s--auth-tokens-reload-interval
Memory watchdog (when a ceiling is set)every 500 ms--memory-max-bytes

Set --flush-interval 0s or --compaction-interval 0s to turn a timer off and drive the work through the admin endpoints instead. See Maintenance for what each step does.

How requests are served

  • One writer per namespace. Writes and DDL take the namespace’s writer lock one at a time. A write that waits longer than --writer-lock-timeout (30 s) fails fast with HTTP 503 instead of queueing forever.
  • Reads do not take the writer lock. HTTP reads, Bolt auto-commit reads and Bolt read transactions run on the latest published snapshot, so a long write never blocks reads and vice versa.
  • Read admission. Concurrent reads are capped process-wide by NAMIDB_MAX_CONCURRENT_QUERIES (default: the number of CPU cores, at least 4) and full scans separately by NAMIDB_MAX_CONCURRENT_SCANS (default 4). A read that cannot get a slot within NAMIDB_QUERY_ADMISSION_WAIT_MS (5000 ms) gets a retryable 503.
  • Group commit (optional). --group-commit-window 2ms (to 5ms) lets writes that arrive together share one WAL append and one manifest commit. Each request is still acknowledged only after its group is durable, and read-your-own-writes holds. Grouped writes share fate if the commit fails. The default 0s commits every write on its own.
  • Read your own writes. A statement sees its own earlier clauses (CREATE … WITH … MATCH finds what it just created), and every request sees all writes acknowledged before it.

Timeouts and caps

LimitDefaultFlagOn breach
Read statement wall clock30s--query-timeout504, code: "timeout"
Write statement wall clock60s--write-timeout504, code: "timeout"; nothing is committed
Rows any read operator may materialise1000000--query-row-cap413, code: "row_cap"
Whole HTTP requestderived (≥ 120 s, and 30 s above the larger statement budget)--http-request-timeout408
HTTP request body for /v0/cypher2 MiB—413
Concurrent HTTP requests1024NAMIDB_HTTP_MAX_CONCURRENCYqueued
Idle Bolt explicit transaction30s--bolt-tx-timeoutrolled back

Set a budget to 0s (or the row cap to 0) to remove it. For a one-off bulk load, either chunk the writes or set NAMIDB_WRITE_TIMEOUT=0s.

Bolt

Add --bolt-listen 0.0.0.0:7687 to accept Neo4j drivers and tools on the same namespace with the same tokens and TLS settings. See Bolt.

TLS

Pass --tls-cert and --tls-key (PEM) to serve HTTPS and Bolt over TLS from the same listeners. Without them the server speaks plaintext; terminate TLS in front of it in that case. See TLS.

Logs

The server logs to stdout through tracing. Control the level with RUST_LOG:

Terminal window
RUST_LOG=info,namidb_storage=debug namidb-server --store "file:///var/lib/namidb?ns=prod"

Statements at or above --slow-query-threshold (default 1s) are logged at WARN with their text (never their parameters). See Monitoring.

Shut down

On SIGTERM or Ctrl-C the server stops accepting connections, drains in-flight HTTP requests and Bolt sessions, and exits. Committed writes are already durable in the WAL, so nothing acknowledged is lost if the process is killed instead; the next start replays the WAL.

Endpoints

MethodPathAuthPurpose
GET/v0/livezpublicLiveness. Takes no lock and reads no namespace.
GET/v0/healthpublicReadiness: manifest version, epoch, writer state, memory. 503 when degraded.
GET/v0/versionpublic{"version":"3.3.0","build_target":"namidb-server"}
GET/v0/metricspublicPrometheus text exposition.
POST/v0/cyphertokenRun one Cypher statement.
POST/v0/admin/flushread-write tokenFlush now.
POST/v0/admin/compactread-write tokenDrain level 0 and wait.
POST/v0/admin/backupread-write tokenOnline backup (needs --backup-target-uri), also as of an earlier instant.
GET/v0/admin/restore-pointsread-write tokenThe restore point window (Restore points).
GET/v0/admin/queriesread-write tokenList in-flight queries.
POST/v0/admin/queries/:id/cancelread-write tokenCancel one.

Request and response formats: HTTP API. Multi-tenant routes: Multi-tenant mode.