SQLiteGraph

Embedded graph database with dual backend architecture, graph algorithms, Cypher-inspired queries, and HNSW vector search.

Positioning: Single-binary embedded database (no server). Persistent storage with atomic batch commits. Graph algorithms + HNSW vector search in one engine. SQLite: stable, mature, and easy to inspect with standard tooling. Native V3: graph-oriented storage with cache, KV, pub/sub, and traversal features. See the benchmarks below for workload-specific behavior.

What's New in v3.0.0

v3.0.0 is the first release that ships the full Cypher engine, the expanded CLI surface, and the cross-session HNSW persistence fix:

• Cypher-inspired MATCH, CREATE, SET, DELETE, multi-hop, variable-depth, star/multi-pattern joins, WHERE with precedence/parentheses, and HNSW vector search via CALL db.index.vector.queryNodes(...).
• CLI coverage for PageRank, betweenness, WCC/SCC, Louvain, label propagation, cycle search, dominators, topological sort, critical path, and HNSW create/insert/search/list/delete.
• Python Graph.query() plus algorithm bindings for SCC, label propagation, cycle search, dominators, critical path, and HNSW index deletion.
• V3 durability fixes and HNSW autoload persistence fixes.

See CHANGELOG for full history.

Backends

Feature	SQLite	Native V3
Status	Stable	Stable
Storage	.db file	.graph file
Capacity model	Storage-limited	Storage-limited
Graph algorithms	35+	35+
HNSW vectors	Yes	Yes
Pub/Sub	Yes	Yes
LRU Cache	No	Yes (v2.1.0)
Parallel BFS	No	Yes (v2.1.1)

Benchmarks

See Architecture for system design details.

Backend Comparison (v2.2.4 — AMD Ryzen 7 7800X3D, tmpfs, Rust 1.95.0):

Benchmark	SQLite	V3	Ratio
BFS 1K nodes / 5K edges	2.5ms	0.45ms	V3 5.5x faster
BFS 10K / 50K	26ms	27ms	~parity
BFS 50K / 250K	160ms	586ms	SQLite 3.6x faster
DFS 1K / 5K	2.4ms	0.46ms	V3 5.2x faster
Point lookup 1K	15µs	82µs	SQLite 5.4x faster
Point lookup 10K	27µs	503µs	SQLite 18x faster
Shortest path 1K	304µs	393µs	SQLite 29% faster

V3 excels at small-scale traversals (contiguous page storage, LRU cache). SQLite dominates at scale (mmap, WAL, FTS5) and point lookups.

Run benchmarks yourself:

git clone https://github.com/oldnordic/sqlitegraph.git
cd sqlitegraph/sqlitegraph-core
cargo bench --features native-v3 --bench backend_comparison

Quick Start

[dependencies]
# SQLite backend (default)
sqlitegraph = "3.0"

# OR Native V3 backend (graph-oriented storage)
sqlitegraph = { version = "3.0", features = ["native-v3"] }

use sqlitegraph::backend::{GraphBackend, NodeSpec};
use sqlitegraph::backend::sqlite::SqliteGraphBackend;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = SqliteGraphBackend::in_memory()?;

    let node_id = backend.insert_node(NodeSpec {
        kind: "User".to_string(),
        name: "Alice".to_string(),
        file_path: None,
        data: serde_json::json!({"age": 30}),
    })?;

    println!("Created node: {}", node_id);
    Ok(())
}

TypedDiGraph (In-Memory)

A lightweight in-memory directed graph with typed node and edge weights, independent of the GraphBackend persistence layer. Useful for build-system DAGs, dependency graphs, and analysis passes that don't need disk storage.

use sqlitegraph::typed_digraph::{TypedDiGraph, NodeIndex, Direction};
use sqlitegraph::typed_digraph::algo::{toposort, tarjan_scc, Dfs};

let mut g = TypedDiGraph::<&str, i32>::new();
let a = g.add_node("compile");
let b = g.add_node("link");
let c = g.add_node("run");
g.add_edge(a, b, 1);
g.add_edge(b, c, 2);

// Topological order
let order = toposort(&g).expect("acyclic");
assert_eq!(order, vec![a, b, c]);

// DFS traversal
let mut dfs = Dfs::new(&g, a);
assert_eq!(dfs.by_ref().collect::<Vec<_>>(), vec![a, b, c]);

New in v3.0.5. See API.md for the full method list.

CLI

cargo install sqlitegraph-cli

# Query
sqlitegraph --db graph.db query "MATCH (n:User) RETURN n.name"

# Algorithms
sqlitegraph --db graph.db bfs --start 1 --depth 3
sqlitegraph --db graph.db algo pagerank --iterations 100

Copy-Paste Demos

Python: CRUD, Query, Algorithms, HNSW

from sqlitegraph import Graph

g = Graph.open_in_memory()

alice = g.add_node(kind="User", name="Alice", data={"age": 30})
bob = g.add_node(kind="User", name="Bob", data={"age": 31})
g.add_edge(alice, bob, "KNOWS")

print(g.query("MATCH (a:User)-[:KNOWS]->(b:User) RETURN a.name, b.name"))
print(g.strongly_connected_components())

idx = g.create_hnsw_index("embeddings", dimension=3, metric="cosine")
idx.insert_vector([1.0, 0.8, 0.1], {"label": "graph databases"})
idx.insert_vector([0.1, 0.2, 1.0], {"label": "baking"})
print(idx.search([1.0, 0.9, 0.0], 1))
g.delete_hnsw_index("embeddings")

CLI: From Empty Database to Query Result

rm -f /tmp/sqlitegraph-demo.db

sqlitegraph --db /tmp/sqlitegraph-demo.db --write insert --kind User --name Alice --data '{"age":30}'
sqlitegraph --db /tmp/sqlitegraph-demo.db --write insert --kind User --name Bob --data '{"age":31}'
sqlitegraph --db /tmp/sqlitegraph-demo.db --write query 'CREATE (1)-[:KNOWS]->(2)'

sqlitegraph --db /tmp/sqlitegraph-demo.db query 'MATCH (a:User)-[:KNOWS]->(b:User) RETURN a.name, b.name'
sqlitegraph --db /tmp/sqlitegraph-demo.db algo scc

Rust: Hybrid Runtime

The Rust example below shows the full mixed-runtime story: ordinary SQLite rows, Native V3 graph metadata, SQLite-backed HNSW vectors, and V3 pub/sub:

cargo run -p sqlitegraph --example hybrid_sqlite_v3_hnsw_pubsub --features native-v3

Python

A Python wrapper around the same Rust engine is published to PyPI as sqlitegraph. The source lives in sqlitegraph-py/ and ships as a single abi3 wheel per platform (Python 3.10+).

pip install sqlitegraph

from sqlitegraph import Graph

g = Graph.open_in_memory()
alice = g.add_node(kind="User", name="Alice", data={"age": 30})
order = g.add_node(kind="Order", name="Order-123")
g.add_edge(alice, order, "placed")

print(g.neighbors(alice))

The Python surface covers node/edge CRUD, BFS/k-hop/shortest path, PageRank, Louvain, connected components, SCC, label propagation, cycle search, dominators, critical path, Graph.query(), HNSW vector indexes, typed exceptions (GraphError, NotFoundError, InvalidArgumentError, BackendError), and type stubs for editors. See sqlitegraph-py/README.md for the full Python API and examples.

Ecosystem

Tools built on SQLiteGraph:

Tool	Purpose	Repository	crates.io
Magellan	Code graph indexing, symbol navigation	github.com/oldnordic/magellan	crates.io/crates/magellan
llmgrep	Semantic code search	github.com/oldnordic/llmgrep	crates.io/crates/llmgrep
Mirage	CFG analysis, path enumeration	github.com/oldnordic/mirage	crates.io/crates/mirage-analyzer
splice	Precision code editing	github.com/oldnordic/splice	crates.io/crates/splice

Documentation

• Architecture - System design
• Manual - API guide
• Query Language - Cypher-inspired query reference
• Changelog - Version history
• SnapshotId Migration Guide - v2.1.2 API changes

License

GPL-3.0-only