HydraDB

HydraDB is an object-store-native distributed graph database written in Rust. It combines durable graph storage on SlateDB with snapshot-consistent OpenCypher queries, GraphBLAS traversal, Neo4j-compatible Bolt connectivity, and an HTTPS query API.

S3-compatible object storage is the durable source of truth. Query nodes and indexers keep only disposable state in memory and on local SSD or NVMe, so they can be replaced or scaled without moving the graph itself.

• Object-store durability. Graph records, WALs, manifests, and immutable traversal indexes live in S3-compatible storage.
• Independent compute. Query nodes and indexers scale separately and can rebuild their local caches from durable state.
• Safe writer handoff. Object-store CAS leases select the active writer for each cell, while SlateDB writer epochs fence stale writers.
• Consistent reads. Every query runs against one pinned SlateDB snapshot. Indexed traversal combines a compiled CSC generation with its visible WAL overlay.
• Graph-native execution. The planner uses property indexes, reverse adjacency, sparse traversal, and SuiteSparse GraphBLAS where appropriate.
• Familiar clients. Applications can use Neo4j drivers over Bolt 5.x or the typed JSON and streaming NDJSON HTTP API.
• Bounded operation. Authentication, authorization, deadlines, result limits, backpressure, cancellation, cache budgets, metrics, and traces are part of the server runtime.

flowchart LR
    C["Applications<br/>Neo4j drivers or HTTPS"]
    SVC["Service or load balancer"]

    subgraph Q["Query tier"]
        Q1["graph-node"]
        Q2["graph-node"]
        QN["graph-node"]
    end

    subgraph I["Indexing tier"]
        IX1["graph-indexer"]
        IXN["graph-indexer"]
    end

    CACHE["Disposable memory and SSD cache"]
    STORE["S3-compatible object storage<br/>WAL, SSTs, leases, CSC generations"]

    C --> SVC
    SVC --> Q1
    SVC --> Q2
    SVC --> QN
    Q1 <--> CACHE
    Q2 <--> CACHE
    QN <--> CACHE
    Q1 <--> STORE
    Q2 <--> STORE
    QN <--> STORE
    IX1 <--> STORE
    IXN <--> STORE

Query nodes serve reads and canonical graph mutations. Indexer workers build immutable CSC generations asynchronously and publish them through atomic object-store pointers. Readers remain correct when an index is absent or behind because the visible WAL tail is applied to the indexed base.

See architecture.md for the storage model, query pipeline, writer coordination, index lifecycle, and failure semantics.

HydraDB requires Rust 1.91 or newer, a C/C++ toolchain, libcypher-parser, and SuiteSparse GraphBLAS.

Ubuntu or WSL:

sudo apt-get update
sudo apt-get install -y \
  build-essential clang libclang-dev cmake pkg-config \
  libcypher-parser-dev libgraphblas-dev \
  curl git python3 python3-venv

The last line is not needed to build, but the steps below use it: curl for the Rust installer and the readiness checks, git to clone, and python3-venv for the Neo4j driver used by scripts/runtime_smoke.sh.

macOS with Homebrew:

xcode-select --install
brew install just cmake pkg-config llvm suite-sparse
brew install cleishm/neo4j/libcypher-parser

# Rust, only if `rustup toolchain list` does not already show a stable toolchain:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

libcypher-parser is not in homebrew-core; the fully-qualified cleishm/neo4j/... name adds the tap automatically. A plain brew install libcypher-parser fails with No available formula.

Rust comes from the official installer rather than Homebrew because the rustup formula is keg-only and no longer ships a rustup-init binary, so brew install rustup leaves nothing named rustup on PATH. rust-toolchain.toml pins channel = "stable", so any rustup-managed stable toolchain works.

No PKG_CONFIG_PATH export is needed: libcypher-parser is not keg-only, so Homebrew links cypher-parser.pc into the default pkg-config search path.

just is the supported command runner for the repository. Install it with cargo install just --locked when your package manager does not provide it. Docker is optional and is used only by MinIO, Neo4j comparison, image-build, and Kubernetes harnesses.

git clone https://github.com/hydra-db/hydradb.git
cd hydradb

just native-check
just smoke

The smoke example creates a local graph, writes and deletes edges, runs a sparse traversal, closes the database, reopens it, and verifies the durable result. The recipe creates and removes an isolated local object-store directory. Use just smoke-graphblas to pin the traversal kernel to SuiteSparse GraphBLAS.

To exercise the same flow against an ephemeral MinIO instance:

just minio-smoke

The following starts a single plaintext development node backed by a local directory. TLS is required by default in deployed environments; plaintext must be enabled explicitly.

mkdir -p .hydradb/store .hydradb/cache
printf '%s\n' 'local-development-token-32-bytes' > .hydradb/auth-token

export CLOUD_PROVIDER=local
export LOCAL_PATH="$PWD/.hydradb/store"
export GRAPH_NAMESPACE=default
export GRAPH_ID=default
export GRAPH_CELL_ID=cell-0
export GRAPH_CELLS=cell-0
export GRAPH_NODE_ID=node-0
export GRAPH_BOLT_NODE_ADDRESSES=node-0=127.0.0.1:7687
export GRAPH_ADVERTISED_BOLT_ADDR=127.0.0.1:7687
export GRAPH_DATA_CACHE_DIR="$PWD/.hydradb/cache"
# Cache chunks default to 4 MiB. Smaller parts reduce cold probe overfetch,
# but can increase later cache misses; benchmark before changing this value.
# The value must be a positive multiple of 1024.
export GRAPH_DATA_CACHE_PART_BYTES=4194304
# Process-wide budget retained by SlateDB disk-cache file caches. Scoped
# runtimes divide it across every possible cell reader and writer.
export GRAPH_DATA_CACHE_MAX_OPEN_FILES=512
export GRAPH_AUTH_TOKEN_FILE="$PWD/.hydradb/auth-token"
export GRAPH_ALLOW_PLAINTEXT=true

# graph-node's async query futures exceed the default thread stack. Without
# this the node builds, serves /readyz, and then aborts on the first query.
export RUST_MIN_STACK=33554432

# macOS: cargo is invoked directly here, so it does not inherit what the
# justfile exports. Linux installs these on default search paths already.
if command -v brew >/dev/null; then
  export BINDGEN_EXTRA_CLANG_ARGS="-I$(brew --prefix)/include"
  export LIBRARY_PATH="$(brew --prefix)/lib"
fi

cargo run --locked --features server-runtime --bin graph-node

The node runs in the foreground and does not return; that is it working, not hanging. Run the checks below from a second shell.

The node listens on:

In another terminal, write and read a small graph through HTTP:

TOKEN='local-development-token-32-bytes'

curl -sS http://127.0.0.1:8443/v1/graphs/default/query \
  -H "Authorization: Bearer $TOKEN" \
  -H 'X-Graph-Namespace: default' \
  -H 'Content-Type: application/json' \
  --data '{"cell_id":"cell-0","query":"CREATE (a {id: 1})-[:FOLLOWS]->(b {id: 2})"}'

curl -sS http://127.0.0.1:8443/v1/graphs/default/query \
  -H "Authorization: Bearer $TOKEN" \
  -H 'X-Graph-Namespace: default' \
  -H 'Content-Type: application/json' \
  --data '{"cell_id":"cell-0","query":"MATCH (a {id: 1})-[:FOLLOWS]->(b) RETURN b.id AS id"}'

The second call returns one row containing {"type":"vertex_id","value":2}. A listening port is not proof the node works; a round-tripped write is.

For a scripted Bolt and HTTP round trip, install the Python Neo4j driver and run. Homebrew's and Debian's Python both refuse a bare pip install under PEP 668, so use a virtualenv (apt-get install -y python3-venv on Debian/Ubuntu):

python3 -m venv /tmp/hydradb-venv && /tmp/hydradb-venv/bin/pip install neo4j

# macOS: this script calls cargo directly, so it does not inherit what the
# justfile exports. Without this it fails at bindgen with
# `'cypher-parser.h' file not found`. Linux needs neither.
if command -v brew >/dev/null; then
  export BINDGEN_EXTRA_CLANG_ARGS="-I$(brew --prefix)/include"
  export LIBRARY_PATH="$(brew --prefix)/lib"
fi

PYTHON=/tmp/hydradb-venv/bin/python bash scripts/runtime_smoke.sh

Prints runtime-smoke-ok. The node's log is at /tmp/sgk-runtime-smoke/node.log; read it first if the script fails.

HydraDB supports a practical OpenCypher subset for graph reads and mutations, including typed relationships, bounded variable-length paths, property and label predicates, ordering, pagination, aggregation, OPTIONAL MATCH, UNION, and batched UNWIND writes.

Applications can connect with a Neo4j driver using a routed URI:

neo4j://127.0.0.1:7687

Use neo4j+s:// with a publicly trusted certificate or neo4j+ssc:// for a self-signed development certificate. Direct bolt:// node addresses are for diagnostics and targeted failure tests; write-capable clustered clients should use routing.

HydraDB includes native snapshot-scoped path procedures:

• algo.SPpaths finds bounded paths between one source and one target.
• algo.SSpaths finds bounded paths from one source.
• algo.MSpaths resolves many indexed source and target values and evaluates them together, avoiding client-side query fan-out.

CALL algo.MSpaths({
  sourceLabel: 'Entity',
  sourceProperty: 'name',
  sourceValues: ['alpha', 'beta', 'gamma'],
  targetValues: ['alpha', 'beta', 'gamma'],
  pairwise: true,
  relTypes: ['RELATES'],
  relDirection: 'both',
  maxLen: 3,
  pathCount: 5,
  fairRelationshipVariants: true,
  resultLimit: 100
})
YIELD path
RETURN path

The procedures use one pinned storage snapshot, compiled GraphBLAS topology when available, the visible WAL overlay, and bounded metadata hydration.

HydraDB exposes two read modes:

HTTPS requests set "consistency": "causal" or "strong" in the request body. Bolt clients set consistency in RUN metadata or hydradb.consistency in transaction metadata. The former turbolay.consistency key remains accepted as a migration alias.

The Helm chart deploys query nodes, indexer workers, services, cache volumes, network policies, disruption budgets, TLS resources, authentication, and optional Prometheus integration.

helm upgrade --install hydradb charts/hydradb \
  --namespace hydradb \
  --create-namespace \
  --values charts/hydradb/examples/values-eks.yaml \
  --atomic \
  --timeout 15m

Copy and edit the example values before deploying. Object-store credentials, bucket names, image references, TLS, advertised Bolt addresses, and workload identity are environment-specific. See the values file comments and the chart templates under charts/hydradb/ for configuration and rollout details.

The public HTTP server exposes GET /healthz. The graph-node and indexer admin servers expose:

GET /readyz
GET /metrics

The runtime emits structured tracing fields for query fingerprints, access paths, cache outcomes, consistency mode, scope, cell, storage sequence, and planner decisions. Build with --features server-runtime,otlp or --features indexer-runtime,otlp to export OpenTelemetry data.

Prometheus duration histograms have deliberately different units. Check each metric's unit before building latency dashboards or alerts.

Run just or just help to list the command surface. Recipes use Bash and run from the repository root. The full native suite requires libcypher-parser and SuiteSparse GraphBLAS.

scripts/ci_local.sh is a compatibility entry point that sets a shared Cargo target directory and delegates to just ci, so the script and Justfile cannot silently drift into different test matrices.

The benchmark recipes intentionally use production-sized defaults and can run for a long time. Override their documented GRAPH_QUERY_* environment variables for a small development sample.

The MinIO recipes create isolated containers, networks, buckets, and temporary configuration files. Their cleanup traps remove those resources unless a recipe-specific keep flag is set. Docker may pull pinned images on the first run.

The scripts below are not all exposed as Just recipes because several operate external infrastructure or incur cloud cost.

just update-slatedb is a maintenance command, not a verification command. It updates the pinned SlateDB dependency in Cargo.lock; review and test the resulting lockfile diff before committing it.

src/core/           configuration, graph model, cache policy, errors
src/shard/          storage lifecycle, reads, writes, queries, path procedures
src/engine/         routing, placement, immutable indexes, index GC
src/query/          OpenCypher parsing, algebra, planning, transport types
src/client/         Bolt, HTTP, authentication, quotas, cursors
src/sparse_kernel/  Rust sparse and SuiteSparse GraphBLAS execution
crates/             placement and telemetry workspace crates
charts/hydradb/     Kubernetes Helm chart
examples/           smoke, import, benchmark, and correctness programs
scripts/            local, MinIO, stress, fencing, and deployment harnesses

Published latency and throughput results are available on the HydraDB benchmark site. To reproduce measurements locally or against S3, use the benchmark commands and scripts documented above.

Issues and pull requests are welcome. Keep changes focused, add regression coverage for behavioral changes, and run just ci before opening a pull request. Changes to storage, fencing, snapshots, routing, or index publication should state the invariant they preserve and include a failure-oriented test.

HydraDB is licensed under the GNU Affero General Public License v3.0.