NopalDB 🌵

High-performance embedded graph database for Python, written in Rust: ACID transactions over an MVCC store, a Cypher-like query language (NQL), vector search, and zero-copy Apache Arrow export for ML pipelines.

Runs in-process — no server to deploy. One pip install, one file on disk.

Install

pip install nopaldb

Prebuilt wheels for Linux (x86_64/aarch64), macOS (Intel/Apple Silicon) and Windows, for CPython 3.10+ (abi3: one wheel per platform covers all versions). Every wheel is installed and tried on its own platform before it is published; the whole test suite runs on Linux x86_64, macOS arm64 and Windows x64.

What the wheel contains

The wheels use redb, the only storage engine since 0.8.0, with every optional tier compiled in (reasoner, OWL import, SHACL, embeddings + HNSW, full-text, algorithms, analytics). Graph.open(...) creates or opens a redb database.

Databases created with 0.5.x (sled engine). sled was removed in 0.8.0. Opening such a database raises an error that says so. Migrate it once with 0.7, the last version that reads sled, then open the copy with 0.8+:

pip install "nopaldb==0.7.*"
python -c "import nopaldb; print(nopaldb.Graph.migrate('old.db', 'new.db')['verified'])"
pip install -U nopaldb

Quickstart

import nopaldb

graph = nopaldb.Graph.open("./data.db")

# ACID transactions
tx = graph.begin_transaction()
alice = tx.add_node("Person", {"name": "Alice", "age": 30})
bob = tx.add_node("Person", {"name": "Bob", "age": 25})
tx.add_edge(alice, bob, "KNOWS")
tx.commit()

# Query with NQL
result = graph.execute_nql("""
    find p.name, p.age
    from (p:Person)
    where p.age > 25
""")
for row in result:
    print(f"{row['p.name']}: {row['p.age']}")

graph.close()

Isolation levels

tx = graph.begin_transaction(isolation="serializable")
# read_committed (default) | repeatable_read | serializable | read_uncommitted

Serializable transactions detect write conflicts and deadlocks; see the durability guarantees and isolation guide.

Arrow / ML pipelines

import pyarrow as pa

arrow_bytes = graph.to_arrow(label="Person")
batch = pa.ipc.open_stream(arrow_bytes).read_next_batch()
df = batch.to_pandas()   # zero-copy into Pandas / Polars / PyTorch pipelines

Good to know

• One process per data directory (embedded file lock). Threads within the process run in parallel — the bindings release the GIL during database calls.
• Use graph.bulk_loader(batch_size) for large ingestions.
• Time travel: since 0.10.2 an NQL query reads the graph as of an earlier commit with at timestamp <ts>, where ts comes from graph.last_commit_timestamp(). Each such query rebuilds the past graph from the whole history, so it is for occasional reads. Garbage collection of old versions (start_auto_gc) is Rust-only.

Links

• Repository & docs: https://github.com/sharop/nopaldb
• Adoption guide: https://github.com/sharop/nopaldb/blob/main/docs/ADOPTION.md
• NQL reference: https://github.com/sharop/nopaldb/blob/main/docs/en/NQL_REFERENCE.md
• Rust crate: https://crates.io/crates/nopaldb

License: MPL-2.0 (the nopaldb library — this repository in its entirety). The companion ecosystem apps (MCP server, NDBStudio) are AGPL-3.0-only and live in their own repositories: https://github.com/Anxious-Mind-Group/nopaldb-mcp · https://github.com/Anxious-Mind-Group/ndbstudio. Releases ≤ 0.4.31 were AGPL-3.0-only. NopalDB™ is a trademark of Sergio Haro Pérez.