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).

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.