# NamiDB reference

An extended companion to `llms.txt`: positioning, benchmarks, an
architecture summary, and an FAQ in one Markdown document.

---

## 1. One-line description

NamiDB is a source-available graph database engine whose on-disk
format lives in object storage: AWS S3, Cloudflare R2, Google Cloud
Storage, Azure Blob, or MinIO. It is embedded like DuckDB, multi-tenant
by namespace, and ships as one engine across Python, Rust, a Docker
daemon, and a managed cloud.

## 2. Positioning (one-liners at three lengths)

- 8 words: Your graph database lives in your S3 bucket.
- 15 words: NamiDB writes Cypher to your S3 bucket. Embedded, server-ready, multi-tenant by namespace, and source-available.
- 30 words: NamiDB is a graph database engine that lives in your bucket (S3, R2, GCS, Azure, MinIO). Embedded like DuckDB, server-ready, multi-tenant by namespace. One engine, any bucket. Source-available under BSL 1.1.

## 3. Boilerplate

NamiDB is a graph database engine that lives in your S3 bucket (AWS
S3, Cloudflare R2, GCS, Azure, MinIO). One engine, three deployments:
embedded as a Python library, self-hosted as a Rust daemon, or
managed on namidb.com. Multi-tenant by namespace. Launched as
source-available v0.1 in May 2026 under BSL 1.1, converting to
Apache 2.0 three years after each release. Built by NamiDB, Inc.

## 4. Architecture summary

- Storage engine on object storage with manifest CAS (compare-and-swap)
  as the only coordination primitive. No external lock service.
- Columnar on-disk format. Ranged reads plus a metadata cache (RFC-003)
  amortise cold latency on WAN.
- Multi-tenant by namespace: strict isolation per tenant inside the
  same bucket.
- Query engine: openCypher dialect, tracking GQL (ISO/IEC 39075).
- Three deployments: Python bindings (abi3 wheels for Linux, macOS
  arm64, Windows x86_64), Rust crate, Rust daemon plus Docker image
  (`namidb-server` exposes a bearer-token REST API on `/v0/*` and,
  since v0.5, an opt-in Bolt v4.4 / 5.0 / 5.4 listener that every
  published Neo4j driver connects to unmodified).
- Concurrent reads since v0.5 (RFC-021): the read path no longer
  takes the writer mutex, so a single namidb-server fans reads
  across every core.
- Storage backends supported: AWS S3, Cloudflare R2, Google
  Cloud Storage, Azure Blob Storage, MinIO, Tigris, LocalStack, local
  filesystem.

## 5. Benchmarks (2026-05-19 publishable sweep)

### Bench A: Engine, LDBC SNB Interactive (scale=1.0, 540 K elements)

Warm p50 (30 warm runs, median across 3 parameter sets):

| Query | NamiDB engine | Kuzu        | Neo4j local (Docker) | Verdict             |
|-------|---------------|-------------|----------------------|---------------------|
| IC02  | 1.09-1.29 ms  | 3.72-5.51 ms| 0.61-0.69 ms         | NamiDB ~3-4x Kuzu   |
| IC07  | 1.19-1.24 ms  | 1.50-1.69 ms| 0.43-0.45 ms         | NamiDB ~1.3x Kuzu   |
| IC08  | 0.95-0.96 ms  | 3.68-3.84 ms| 0.38-0.43 ms         | NamiDB ~4x Kuzu     |
| IC09  | 2.88-5.15 ms  | 6.55-7.41 ms| 0.84-1.15 ms         | NamiDB ~1.4-2x Kuzu |

Cold p50 (first query after a fresh mount): NamiDB cold is still bound
by Parquet decode plus first-time SST scan, 5-50x slower than Kuzu and
Neo4j warm-disk paths. Neo4j local wins everything because it runs on
attached NVMe with a tuned B-tree. NamiDB's value is not engine-only.
It is object storage, multi-tenant, zero-egress.

Methodology: synthetic LDBC SNB Interactive datagen (deterministic).
Hardware: MacBook M4 Pro (12 cores, macOS 24.1.0). Storage during
query benches: `object_store::InMemory`. Build: engine commit 1f7166c.

### Bench B: Cloud (NamiDB fsn1 to R2 EU vs Neo4j Aura GCP us-east1)

Server-side warm p50 (wall-clock minus WAN floor):

| Query | NamiDB cloud | Neo4j Aura | NamiDB / Aura      |
|-------|--------------|------------|--------------------|
| IC02  | ~2 ms        | ~12 ms     | 6x faster          |
| IC07  | <1 ms        | ~12 ms     | within WAN floor   |
| IC08  | <1 ms        | ~11 ms     | within WAN floor   |
| IC09  | 8-18 ms      | 12-13 ms   | comparable         |

Wall-clock favours Aura from this LATAM laptop because Aura's region
(GCP us-east1, RTT ~72 ms) is closer than fsn1 (RTT ~205 ms). That is
an accident of test geography, not architecture. Stripped of the WAN
floor, NamiDB cloud's engine, worker, and R2 path is competitive-to-
better than Aura. Cold IC09 still bites where Aura's tuned NVMe is
cheaper first-touch (~370 ms server-side vs ~25 ms).

### Bench D: Bulk write throughput (540 K elements)

Engine-level (laptop):

| Engine        | Operation                  | Time  | Elements / second |
|---------------|----------------------------|-------|-------------------|
| Kuzu          | COPY (CSV to local disk)   | 0.70s | 769,821           |
| NamiDB engine | bulk_load_inmemory         | 1.37s | 394,138           |

Kuzu wins engine-level writes by ~2x. Its columnar batch encoder is
tuned for the offline-import case.

Cloud-level (NamiDB only; Aura `LOAD CSV` is bottlenecked by Bolt):

| Client to R2 EU                     | RTT     | Time   | Elements / second |
|-------------------------------------|---------|--------|-------------------|
| Hetzner Falkenstein (in-region)     | ~3 ms   | 10.5 s | 51,522            |
| MacBook M4 Pro laptop (LATAM)       | ~205 ms | 16.9 s | 31,870            |

Multipart PUT (5 MiB parts, 8-way concurrency) eats most of the WAN-
bound serial-PUT overhead; in-region adds another 1.6x.

### Bench F: R2 PUT / GET microbench (laptop to R2 EU)

| Object size | PUT p50  | GET cold p50 | GET warm p50 | TTFB p50 |
|-------------|----------|--------------|--------------|----------|
| 1 KiB       | 845 ms   | 432 ms       | 155 ms       | n/a      |
| 64 KiB      | 754 ms   | 527 ms       | 152 ms       | n/a      |
| 1 MiB       | 1.38 s   | 752 ms       | 235 ms       | 141 ms   |
| 16 MiB      | 1.56 s   | 1.70 s       | 1.32 s       | 170 ms   |
| 100 MiB     | 6.82 s   | 8.76 s       | 8.52 s       | 156 ms   |

TTFB is ~140-170 ms constant regardless of object size, the RTT from
LATAM to the nearest Cloudflare PoP. Edge-cache effect: small reads
are 3x faster warm. The bandwidth-bound regime kicks in at 16 MiB; the
100 MiB cold GET sustains about 96 Mbps.

### Reproducibility

Benchmark harness, dataset generator, and raw JSONs are reproducible
at https://github.com/namidb/namidb/tree/main/bench . Engine commit
1f7166c, cloud commit 34eec6d, published 2026-05-19.

### Not yet measured (published explicitly)

- The remaining 10 LDBC Complex Read queries (IC01, IC03-IC06, IC10-IC14).
- LDBC Short Reads (IS1-IS7).
- Classical LDBC SF1 (11 M elements) from the official Hadoop datagen.
- Aura in `gcp-europe-west1` for a symmetric WAN test from the same client.
- A second in-region anchor (for example AWS Frankfurt) for the multipart write lane.
- Per-tenant cloud cost, once the cloud is in public beta.

## 6. Installation

```bash
# Python: official bindings
pip install namidb

# Rust: embedded crate
cargo add namidb

# Docker: self-hosted daemon
docker run -p 7475:7475 namidb/namidb-server:0.5.1
```

Managed cloud (`NamiDB Cloud`) is in private beta. Request access
via the waitlist on https://namidb.com .

Developer documentation: https://docs.namidb.com .

## 7. License

Business Source License 1.1, automatically converting to Apache 2.0
three years after each release. Source-available from day one, free
for non-production and most production use. A commercial license is
required only to embed NamiDB in a closed-source product or
redistribute it as a managed service. Contact licensing@namidb.com .

## 8. Company

NamiDB is built by NamiDB, Inc., a Delaware company. Founder:
Matías Fonseca.

## 9. Contact

- General: hello@namidb.com
- Press and analysts: press@namidb.com (kit at namidb.com/press)
- Design partners (private beta): partners@namidb.com
- Security (coordinated disclosure): security@namidb.com
- Hiring: hiring@namidb.com (open roles at namidb.com/careers)
- Commercial licensing: licensing@namidb.com

## 10. FAQ

**What is NamiDB?**
NamiDB is a source-available graph database engine that runs on
object storage. It is embedded like DuckDB, multi-tenant by namespace,
uses one engine across AWS S3, Cloudflare R2, GCS, Azure Blob, MinIO.

**Where does NamiDB store its data?**
Directly in your object-storage bucket. NamiDB writes its on-disk
format to S3, R2, GCS, Azure Blob, MinIO, Tigris, or LocalStack. There
is no separate stateful service to operate. Your bucket is the database.

**What query language does NamiDB support?**
Cypher. NamiDB targets the openCypher dialect and is positioning
toward GQL (ISO/IEC 39075) as the standard stabilises.

**How do I install NamiDB?**
`pip install namidb` for Python, `cargo add namidb` for embedded Rust,
or the `namidb-server` Docker image for a self-hosted daemon.

**What license is NamiDB released under?**
Business Source License 1.1, automatically converting to Apache 2.0
three years after each release.

**Who builds NamiDB?**
NamiDB, Inc., a Delaware company. NamiDB launched as
source-available v0.1 in May 2026.

**Is there a hosted version?**
Yes. NamiDB Cloud, a managed multi-tenant service, is in private
beta on namidb.com. Request access from the waitlist on the homepage.