farhansyah/nodedb repository overview

NodeDB replaces the combination of PostgreSQL + pgvector + Redis + Neo4j + ClickHouse + Elasticsearch with a single process. Graph queries that feed vector search, full-text ranking, and columnar aggregation execute in one engine with shared storage, shared memory, and one planner.

⁠Quick Start

docker run -d \
  --name nodedb \
  -p 6432:6432 \
  -p 6433:6433 \
  -p 6480:6480 \
  -v nodedb-data:/var/lib/nodedb \
  farhansyah/nodedb:latest

Connect with any PostgreSQL client:

psql -h localhost -p 6432

CREATE COLLECTION users;

INSERT INTO users (name, email, age) VALUES ('Alice', '[email protected]', 30);

-- Object literal syntax
INSERT INTO users { name: 'Bob', email: '[email protected]', age: 25 };

SELECT * FROM users WHERE age > 25;

New here? Start with the Quickstart⁠ on the official documentation site.

⁠Image

The image ships only glibc, libgcc, ca-certificates, and the nodedb binary. No shell, no package manager, no curl. Healthchecks are handled by the binary's built-in nodedb healthcheck subcommand.

⁠Tags

⁠Requirements

• Linux kernel ≥ 5.1 (io_uring) on the host. Docker Desktop on macOS/Windows works (the embedded Linux VM satisfies this).
• For best performance with io_uring, run with elevated capabilities:

  docker run --cap-add SYS_NICE --ulimit memlock=-1:-1 ...
  

  Copy

⁠Ports

⁠Volumes

/var/lib/nodedb       # data directory (WAL, segments, snapshots)

Named volumes (recommended) work out of the box — they inherit nonroot ownership from the image:

docker run -v nodedb-data:/var/lib/nodedb ...

Bind mounts require manual ownership setup since the container runs as uid 65532:

sudo chown -R 65532:65532 /path/on/host
docker run -v /path/on/host:/var/lib/nodedb ...

⁠Environment Variables

⁠Logs

NodeDB writes structured logs to stderr. Capture them with the standard Docker tooling:

docker logs -f nodedb                    # follow
docker logs --tail 100 nodedb            # last 100 lines

# JSON output for log aggregators (Loki, Datadog, etc.)
docker run -e NODEDB_LOG_FORMAT=json ... farhansyah/nodedb:latest

⁠Healthcheck

The image includes a built-in HEALTHCHECK that probes /health every 10 seconds. Status is visible via docker ps:

docker ps --filter name=nodedb --format 'table {{.Names}}\t{{.Status}}'

To run the probe manually:

docker exec nodedb /usr/local/bin/nodedb healthcheck

⁠Clustering

For a multi-node Raft cluster, mount a config file specifying peers:

docker run -d \
  --name nodedb-1 \
  -p 6432:6432 -p 6433:6433 -p 6480:6480 \
  -v nodedb-1-data:/var/lib/nodedb \
  -v $(pwd)/node1.toml:/etc/nodedb/nodedb.toml:ro \
  -e NODEDB_CONFIG=/etc/nodedb/nodedb.toml \
  farhansyah/nodedb:latest

Full clustering setup, joining new nodes, TLS bootstrapping, and operator commands (regen-certs, rotate-ca, join-token) are documented at nodedb.dev/docs⁠.

⁠Performance Note

The Docker image is provided for convenience. For maximum performance — especially io_uring throughput, jemalloc arena pinning, and TPC core affinity — run the native binary directly. Container runtime overhead and cgroup limits can interfere with the Thread-per-Core data plane. See the GitHub repo⁠ for native install instructions.

⁠Engines

Detailed engine docs at nodedb.dev/docs⁠.

⁠Wire Protocols

NodeDB speaks six protocols on a single binary: pgwire (PostgreSQL), HTTP/REST, WebSocket, RESP (Redis), ILP (InfluxDB line protocol), and native MessagePack.

⁠Release Status

v0.1.0 — Public Beta (2026-05-07). All eight engines are feature-complete. Wire protocols (pgwire, HTTP, native, RESP, ILP, WebSocket) are stable — clients written against 0.1.0 will keep working through 1.0.

v1.0.0 — Production-ready (target: 2026-07-07). API/SQL/wire-protocol/on-disk-format stability, performance SLAs, and a third-party security audit.

⁠Links

• Documentation: nodedb.dev/docs⁠
• Source: github.com/NodeDB-Lab/nodedb⁠
• Issues: github.com/NodeDB-Lab/nodedb/issues⁠
• Discord: discord.gg/s54gDMVc7B⁠
• NodeDB-Lite (embedded): github.com/NodeDB-Lab/nodedb-lite⁠
• ndb CLI: github.com/NodeDB-Lab/nodedb-cli⁠

⁠Contributors

⁠

⁠License

NodeDB uses a dual-license model:

• Shared engine crates (nodedb-types, nodedb-vector, nodedb-graph, nodedb-fts, nodedb-spatial, nodedb-codec, nodedb-columnar, nodedb-array, nodedb-sql, nodedb-client, nodedb-query, nodedb-strict) — Apache 2.0⁠.
• Server crates (nodedb, nodedb-wal, nodedb-raft, nodedb-cluster, nodedb-bridge, nodedb-mem, nodedb-crdt) — Business Source License 1.1⁠. Free for any use except offering NodeDB as a hosted database service. Converts to Apache 2.0 on 2030-05-01.