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

Benchmarks

See Architecture for system design details.

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

V3 excels at small-scale traversals. SQLite dominates at larger graph sizes and point lookups.

Run benchmarks yourself:

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

See examples/ for reproducible performance tests.

Quick Start

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

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

use sqlitegraph_core::backend::{GraphBackend, NodeSpec};
use sqlitegraph_core::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.

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 CLI Demo

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

Hybrid Runtime Demo

This crate includes a runnable demo that combines 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

Safety Invariants

• Orphan edges are detected by verifying every edge endpoint references a stored entity before any reasoning or subgraph extraction runs.
• Duplicate edges (identical (from,to,type) tuples) are tallied so traversal/pipeline counts stay deterministic and regressions surface quickly.
• Invalid label/property references (metadata rows pointing at missing entities) are reported by the safety-check helpers.
• Integrity sweeps perform a deep table walk (entities/edges/labels/properties), verifying sorted IDs, valid JSON payloads, and metadata references before committing to pipelines or migrations.

DSL Constraints

• Supported clauses are limited to deterministic pattern, k-hop, filter type=…, and score steps; ordering matters and only one filter clause is allowed.
• Combination syntax (CALLS*2, CALLS->USES) must not introduce conflicting filters or unknown tokens—ambiguous or unsupported input causes parser errors surfaced to the CLI/tests.

Performance & Instrumentation

Performance thresholds in sqlitegraph_bench.json gate releases. Benchmarks produce HTML reports under target/criterion. Use cargo bench --bench bench_insert (etc.) to isolate suites. The bench_driver binary runs all benches sequentially and surfaces pass/fail summaries.

Runtime instrumentation is exposed through the core APIs used by benchmarks and integration tests: prepare/execute counts, transaction begins/commits/rollbacks, and cache hits/misses can be captured while reproducing workloads.

Schema Compatibility Matrix

Upgrade workflow:

1. Inspect the database with sqlitegraph --db <path> status.
2. Review pending migrations through the library migration helpers.
3. Apply migrations atomically through the library helper; history entries are appended automatically.

Ecosystem

Tools built on SQLiteGraph:

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