Configuration

NamiDB is configured via environment variables and (for the server) a set of command-line flags that mirror them. The defaults are fine for almost every workload; the knobs below are what you reach for when chasing performance or behavior.

The list below is sourced from the project README, the namidb-server README, and the CHANGELOG.

Engine env vars

These apply anywhere the engine runs — embedded library, CLI, namidb-server, Python client.

Variable	Default	What it does
NAMIDB_ADJACENCY	ON	CSR adjacency in RAM, shared across snapshots (RFC-018).
NAMIDB_NODE_CACHE	ON	Cross-snapshot NodeView lookup cache (RFC-019).
NAMIDB_SST_CACHE	ON	SST body, decoded edge property streams, and the parsed EdgeSstReader (RFC-020).
NAMIDB_FACTORIZE	OFF	Factorized intermediate results in the executor (RFC-017). Wins on path-heavy queries.
NAMIDB_WCOJ	OFF	Worst-case-optimal join via leapfrog triejoin (RFC-024). Requires NAMIDB_FACTORIZE=1. Opt-in.
NAMIDB_PROFILE_DUMP	OFF	Dump per-stage profile counters to stderr after each query.

Any value other than 0 / OFF enables a flag. Set 1 or ON to turn one on.

Server env vars and flags

These are read by namidb-server only. Every flag has a matching env var; the flag wins when both are set.

Env var	Flag	Default	What it does
NAMIDB_STORE	--store	(required)	Storage URI, e.g. s3://bucket/data?ns=prod&region=us-east-1. Same grammar as the Python client and CLI.
NAMIDB_LISTEN	--listen	0.0.0.0:8080	TCP bind address for the HTTP API.
NAMIDB_AUTH_TOKEN	--auth-token	unset (open)	Bearer token. When unset the server boots in unauthenticated mode with a loud warning.
NAMIDB_FLUSH_INTERVAL	--flush-interval	30s	Background memtable → L0 flush cadence. Set to 0s to disable and call /v0/admin/flush manually.
NAMIDB_BOLT_LISTEN	--bolt-listen	unset (HTTP only)	Opt-in TCP bind address for the Bolt 4.4 / 5.0 / 5.4 listener. Example: 0.0.0.0:7687.

Backend credentials

These are not NamiDB-specific; they’re the standard cloud-vendor env vars the underlying object_store client reads.

Backend	Variables
AWS S3	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (optional), AWS_DEFAULT_REGION
Cloudflare R2	AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (R2 token id / secret), plus URI endpoint=...&region=auto
Google Cloud Storage	GOOGLE_APPLICATION_CREDENTIALS (service-account JSON path) — or pass ?service_account=... in the URI
Azure Blob	AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCESS_KEY (and friends). ?use_emulator=true for Azurite.
MinIO / LocalStack	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, plus URI endpoint=...&allow_http=true

IAM permissions NamiDB asks for on object stores: GetObject, PutObject, DeleteObject, ListBucket. Nothing else.

Logging

The Rust binaries (namidb, namidb-server) honor RUST_LOG. The docker-compose.yml shipped in the repo sets RUST_LOG=info on the namidb-server service.

RUST_LOG=info,namidb_storage=debug namidb-server --store memory://demo

Common combinations

Maximum read performance

NAMIDB_ADJACENCY=1 \
NAMIDB_NODE_CACHE=1 \
NAMIDB_SST_CACHE=1 \
NAMIDB_FACTORIZE=1 \
namidb-server --store "$NAMIDB_STORE" --listen 0.0.0.0:8080 --auth-token "$NAMIDB_AUTH_TOKEN"

Opt into worst-case-optimal join

For cyclic Cypher patterns (triangles, k-cliques, k-cycles):

NAMIDB_FACTORIZE=1 NAMIDB_WCOJ=1 namidb-server …

Without NAMIDB_WCOJ=1 the planner stays on the binary hash-join chain (the default). With it, contiguous Expand chains that form a cycle fold into a single MultiwayJoin running leapfrog triejoin.

Profile a query

NAMIDB_PROFILE_DUMP=1 namidb run --store memory://demo \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b"

Profile counters print to stderr after the query.

Externalize the flush

Disable the background loop and drive flushes from a sidecar:

namidb-server \
  --store "$NAMIDB_STORE" \
  --listen 0.0.0.0:8080 \
  --auth-token "$NAMIDB_AUTH_TOKEN" \
  --flush-interval 0s

# from cron / sidecar
curl -s -X POST http://localhost:8080/v0/admin/flush \
  -H "Authorization: Bearer $NAMIDB_AUTH_TOKEN"

What’s next

• HTTP server — every server flag in context.
• Storage backends — credential hand-off per backend.
• Docker + MinIO — a concrete example of every env var above in one compose file.