Self-hosted NamiDB
NamiDB is a property-graph database that keeps its data in object storage. You write Cypher; the engine lays nodes and relationships out as immutable columnar files in a bucket (or a local folder), and that bucket is the only source of truth. There is no separate metadata service and no consensus cluster: commits are coordinated with conditional writes on the bucket itself.
These pages document engine release 3.3.0 (2026-11-03). Every command, query and response shown here was run against the 3.2.0 release artifacts, and those that later releases change (version strings, the per-query memory budget, restore points, timeouts and cancel) again against 3.2.1 and 3.3.0.
Ways to run it
The same engine ships in several shapes. Pick the boundary you want.
| Shape | What you get | Vector / full-text indexes |
|---|---|---|
Python wheel — pip install namidb | The engine inside your Python process. Sync and asyncio APIs, Arrow / pandas / polars results. | Included |
Server — namidb-server (Docker image or release binary) | HTTP JSON API and an optional Bolt listener for Neo4j drivers. Auth, TLS, metrics, multi-tenant mode, backup / restore endpoints. | Included |
CLI — namidb | One-shot queries, plan inspection, backup / restore, Markdown vault ingestion. | Not included in the release archive |
MCP server — namidb-mcp | A read-only Model Context Protocol server over stdio for AI agents. | Not included in the release archive |
| Rust crates — git dependency | The storage and query crates embedded directly. Unstable, low-level API. | Opt-in Cargo features |
Where to start
- Install — pip, Docker, release binaries, or from source.
- Your first query — an in-memory graph in under a minute, no credentials.
- HTTP server — run
namidb-serverfor other processes and languages. - Supported Cypher — exactly what the query engine accepts.
- Configuration reference — every flag and environment variable with its default.
What is in the box
- Cypher / GQL property graph.
MATCH,OPTIONAL MATCH,MERGE,FOREACH,CALL { … }subqueries,EXISTS { … }, label disjunction(n:A|B), variable-length paths (*,*1..$n),shortestPath, aggregates, list comprehensions and more. See Cypher. - Schema when you want it. Unique constraints (single and composite),
equality indexes (single and composite),
SHOW CONSTRAINTS/SHOW INDEXES. See Schema. - Vector, full-text and hybrid search. Cosine / dot / Euclidean KNN, a persistent ANN index, BM25 with phrases and prefixes, and Reciprocal Rank Fusion. See Search.
- Graph algorithms. PageRank, connected components, Louvain, label propagation, betweenness, triangle count, shortest paths and FastRP. See Algorithms.
- Real auth. Static tokens with roles and namespace scopes, optional OIDC/JWT, an optional external policy hook. See Authentication.
- Operations built in. Online backups, restore, compaction, Prometheus metrics, a slow-query log, and an in-flight query list with cancel. See Operations.
Core concepts
- Namespace. One independent graph: its own manifest, write-ahead log,
data files and writer. Names match
[a-z0-9][a-z0-9_-]{0,62}. A storage URI names the namespace with?ns=<name>. - One writer per namespace. Any number of readers, one writer. A process that opens a namespace for writing claims an epoch and fences the previous writer. See Multi-tenant mode for how this plays out with many namespaces.
- Durable on return. A Cypher write is committed (WAL append plus a conditional manifest-pointer write) before the call returns. Flushing turns the in-memory table into immutable data files; compaction merges them. See Maintenance.
- Storage requirement. The bucket must honour PUT-if-absent
(
If-None-Match: *). AWS S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, Tigris and current MinIO do. See Object stores.
License
The engine is source-available under the Business Source License 1.1
(BSL 1.1). You may copy, modify and use it for non-production purposes, and
the Additional Use Grant permits production use as part of your own product
or service, as long as that product is not itself a graph database product
and you do not offer NamiDB to third parties as a hosted or managed service.
Each version converts to the Apache License 2.0 on May 18, 2029, or on the
fourth anniversary of that version’s first public release if that is
earlier. The LICENSE
file is the authoritative text. For uses outside the grant, a commercial
license is available from NamiDB, Inc. at
info@namidb.com.
Versioning
The released CLI and server binaries, the HTTP / Bolt / Cypher surfaces, the
PyPI package, the container images and the on-disk formats follow Semantic
Versioning; breaking changes bump the major version. The Rust workspace
crates are not published to crates.io and their pub items are not yet a
stable API. See the changelog and
Upgrades.