NodeDB

A local-first, real-time, edge-to-cloud hybrid database for multi-modal workloads.

NodeDB provides Vector, Graph, Document (schemaless + strict), Columnar (with Timeseries and Spatial profiles), Key-Value, and Full-Text Search engines in a single Rust binary. All engines share the same storage, memory, and query planner — cross-engine queries execute in one process with zero network hops.

Engines

Engine	What it does
Vector	HNSW index with SQ8/PQ/IVF-PQ quantization and adaptive bitmap filtering
Graph	CSR adjacency index, 13 algorithms, Cypher-subset MATCH, GraphRAG fusion
Document	Schemaless (MessagePack + CRDT sync) or Strict (Binary Tuples, O(1) field access)
Columnar	Per-column compression (ALP, FastLanes, FSST), predicate pushdown, HTAP bridge
Timeseries	Columnar profile with ILP ingest, continuous aggregation, PromQL, 12 SQL functions
Spatial	R*-tree, geohash, H3, OGC predicates, hybrid spatial-vector search
Key-Value	Hash-indexed O(1) lookups, TTL, secondary indexes, SQL-queryable
Full-Text Search	BM25 + 15-language stemming + fuzzy + hybrid vector fusion

Architecture

NodeDB uses a three-plane hybrid execution model:

• Control Plane (Tokio + DataFusion) — SQL parsing, query planning, connection handling. Send + Sync.
• Data Plane (Thread-per-Core + io_uring) — Physical execution, storage I/O, SIMD math. !Send.
• Event Plane (Tokio, bounded event bus) — AFTER trigger dispatch, CDC change streams, cron scheduler, durable pub/sub, webhook delivery. Consumes events from the Data Plane and dispatches side effects back through the Control Plane.

The planes communicate only through bounded lock-free SPSC ring buffers. See Architecture for the full design.

Deployment Modes

• Origin (server) — Full distributed database. Multi-Raft consensus, Thread-per-Core data plane with io_uring, PostgreSQL-compatible SQL over pgwire. Horizontal scaling with automatic shard balancing.
• Origin (local) — Same binary, single-node. No cluster overhead. Like running Postgres locally.
• NodeDB-Lite (embedded) — In-process library for phones, browsers (WASM), and desktops. All engines run locally with sub-millisecond reads. Offline-first with CRDT sync to Origin.

Application code is the same across all three modes — the NodeDb trait exposes identical methods whether backed by an in-process Lite engine or a remote Origin server.

Quick Start

# Build
cargo build --release

# Run single-node server
./target/release/nodedb

# Connect with the CLI
./target/release/ndb

# Or connect with psql
psql -h localhost -p 6432

-- Create a document collection and insert data
CREATE COLLECTION users TYPE document;
INSERT INTO users { name: 'Alice', email: 'alice@example.com' };
SELECT * FROM users WHERE name = 'Alice';

-- Create a vector index and search
CREATE COLLECTION articles TYPE document;
CREATE VECTOR INDEX ON articles FIELDS embedding DIMENSION 384;
SELECT * FROM articles WHERE embedding <-> $query_vec LIMIT 10;

See Getting Started for a fuller walkthrough.

Capabilities

Programmability

• Stored Procedures — CREATE [OR REPLACE] PROCEDURE with BEGIN...END bodies. Full procedural SQL: IF/ELSIF/ELSE, FOR, WHILE, LOOP, DECLARE, RETURN. Execution budgets via WITH (MAX_ITERATIONS, TIMEOUT). SECURITY DEFINER execution model.
• User-Defined Functions — CREATE [OR REPLACE] FUNCTION with SQL expression bodies or procedural BEGIN...END bodies. Volatility levels (IMMUTABLE, STABLE, VOLATILE). Expression UDFs inline directly into DataFusion query plans. GRANT EXECUTE ON FUNCTION.
• Triggers — CREATE TRIGGER with ASYNC (default, Event Plane), SYNC (ACID, same transaction), and DEFERRED (at COMMIT time) execution modes.

Real-Time (powered by the Event Plane)

• CDC Change Streams — CREATE CHANGE STREAM with consumer group offset tracking, per-partition offsets, log compaction, and retention. External delivery via webhook (retry + idempotency headers) or Kafka bridge (transactional exactly-once, feature-gated). ~1-5ms write-to-consumer latency.
• Streaming Materialized Views — CREATE MATERIALIZED VIEW ... STREAMING AS SELECT ... FROM <stream>. Continuously-updating aggregation with O(1) incremental maintenance per event. Replaces ksqlDB.
• Durable Topics — CREATE TOPIC with PUBLISH TO for persistent pub/sub. Consumer groups with offset tracking. Messages survive disconnect.
• Cron Scheduler — CREATE SCHEDULE ... CRON '...' AS BEGIN...END for recurring SQL jobs. Per-collection affinity, leader-aware in distributed mode.
• LISTEN/NOTIFY — PostgreSQL-compatible, extended to cluster-wide delivery.

Operations

• Backup/Restore — BACKUP TENANT <id> TO '<path>' and RESTORE TENANT <id> FROM '<path>'. Encrypted (AES-256-GCM), serialized as MessagePack. DRY RUN mode for pre-restore validation.
• Storage conversion — CONVERT COLLECTION <name> TO document|strict|kv for live in-place storage mode migration.

Documentation

• Getting Started — Build, run, connect, first queries
• Architecture — How the three-plane execution model works
• Engine Guides — Deep dives into each engine
• Security — Auth, RBAC, RLS, encryption
• Real-Time — LIVE SELECT, CDC, pub/sub
• NodeDB-Lite — Embedded edge database
• CLI (ndb) — Terminal client

API reference will be published at nodedb-docs (coming soon). In the meantime, cargo doc --open generates full Rust API documentation.

Building

cargo build --release           # Build all crates
cargo test --all-features       # Run all tests
cargo fmt --all --check         # Check formatting
cargo clippy --all-targets -- -D warnings  # Lint

Status

NodeDB is pre-release. All engines are implemented and tested, but the system has not yet been deployed in production.

License

NodeDB is licensed under the Business Source License 1.1. You can use NodeDB for any commercial purpose — SaaS products, AI platforms, internal tools, self-hosted deployments, anything. The only restriction is offering NodeDB itself as a hosted database service (DBaaS) or commercial database tooling; that requires a commercial license. Converts to Apache 2.0 on 2030-01-01.