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
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:7687Or with the official image (see Install):
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:
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 purposePick one:
| Option | Use it for |
|---|---|
--auth-token / NAMIDB_AUTH_TOKEN | One read-write bearer token. |
--auth-tokens-file | Several named tokens, read-only roles, namespace scopes, hot reload. |
--jwt-jwks-url and friends | OIDC / JWT bearer tokens (build with the jwt feature). |
--no-auth | Local 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
| Task | Default | Flag |
|---|---|---|
| Flush the in-memory table to level-0 data files | every 30s, and as soon as it holds 64 MiB | --flush-interval, --memtable-flush-bytes |
| Compact level-0 files and sweep unreachable objects | every 300s, and as soon as a bucket holds 8 L0 files | --compaction-interval, --compaction-l0-trigger |
| Delete objects no live manifest references | during the sweep, only when older than 24h | --sweep-min-age, --sweep-delete |
Reload --auth-tokens-file | every 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 byNAMIDB_MAX_CONCURRENT_SCANS(default 4). A read that cannot get a slot withinNAMIDB_QUERY_ADMISSION_WAIT_MS(5000 ms) gets a retryable 503. - Group commit (optional).
--group-commit-window 2ms(to5ms) 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 default0scommits every write on its own. - Read your own writes. A statement sees its own earlier clauses
(
CREATE … WITH … MATCHfinds what it just created), and every request sees all writes acknowledged before it.
Timeouts and caps
| Limit | Default | Flag | On breach |
|---|---|---|---|
| Read statement wall clock | 30s | --query-timeout | 504, code: "timeout" |
| Write statement wall clock | 60s | --write-timeout | 504, code: "timeout"; nothing is committed |
| Rows any read operator may materialise | 1000000 | --query-row-cap | 413, code: "row_cap" |
| Whole HTTP request | derived (≥ 120 s, and 30 s above the larger statement budget) | --http-request-timeout | 408 |
HTTP request body for /v0/cypher | 2 MiB | — | 413 |
| Concurrent HTTP requests | 1024 | NAMIDB_HTTP_MAX_CONCURRENCY | queued |
| Idle Bolt explicit transaction | 30s | --bolt-tx-timeout | rolled 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:
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
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /v0/livez | public | Liveness. Takes no lock and reads no namespace. |
GET | /v0/health | public | Readiness: manifest version, epoch, writer state, memory. 503 when degraded. |
GET | /v0/version | public | {"version":"3.3.0","build_target":"namidb-server"} |
GET | /v0/metrics | public | Prometheus text exposition. |
POST | /v0/cypher | token | Run one Cypher statement. |
POST | /v0/admin/flush | read-write token | Flush now. |
POST | /v0/admin/compact | read-write token | Drain level 0 and wait. |
POST | /v0/admin/backup | read-write token | Online backup (needs --backup-target-uri), also as of an earlier instant. |
GET | /v0/admin/restore-points | read-write token | The restore point window (Restore points). |
GET | /v0/admin/queries | read-write token | List in-flight queries. |
POST | /v0/admin/queries/:id/cancel | read-write token | Cancel one. |
Request and response formats: HTTP API. Multi-tenant routes: Multi-tenant mode.