hydra-db/hydradb

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.

Storage and compute are fully disaggregated. S3-compatible object storage is the durable source of truth, and compute runs as two independent roles: data nodes (graph-node) serve queries and canonical mutations, while indexers (graph-indexer) build immutable traversal indexes in the background. Both keep only disposable state in memory and on local SSD or NVMe, so they can be replaced or scaled without moving the graph itself.

Why HydraDB

• Object-store durability. Graph records, WALs, manifests, and immutable

• Independent compute. Data nodes and indexers scale separately and can

• Safe writer handoff. Object-store CAS leases select the active writer for

• Consistent reads. Every query runs against one pinned SlateDB snapshot.

• Graph-native execution. The planner uses property indexes, reverse

• Familiar clients. Applications can use Neo4j drivers over Bolt 5.x or the

• Bounded operation. Authentication, authorization, deadlines, result

Architecture

flowchart TB
    C["Applications
Neo4j drivers or HTTPS"]
    SVC["Service or load balancer"]
subgraph Q["Data tier — graph-node"]
        direction LR
        subgraph N1["graph-node"]
            Q1["query + mutation engine"]
            S1["local SSD / NVMe cache"]
            Q1 <--> S1
        end
        subgraph N2["graph-node"]
            Q2["query + mutation engine"]
            S2["local SSD / NVMe cache"]
            Q2 <--> S2
        end
    end
subgraph I["Indexing tier — graph-indexer"]
        IX1["graph-indexer"]
        IXN["graph-indexer"]
    end
STORE["S3-compatible object storage
WAL, SSTs, leases, CSC generations"]
C --> SVC
    SVC --> N1
    SVC --> N2
    N1 <--> STORE
    N2 <--> STORE
    IX1 <--> STORE
    IXN <--> STORE

Each data node owns a private local SSD/NVMe cache; the object store is the shared layer beneath the whole tier and the only durable copy of the graph.

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

Getting Started

There are two ways to bring up a single development node: the published Docker image, or a build from source. Either way, once the node is listening, use Verify a running node to confirm it works — a listening port is not proof; a round-tripped write is. TLS is required by default in deployed environments, so the local flows below enable plaintext explicitly.

docker pull ghcr.io/hydra-db/hydradb:latest

no matching manifest for linux/arm64/v8 in the manifest list entries

docker buildx imagetools inspect ghcr.io/hydra-db/hydradb:latest

mkdir -p hydradb-data/store hydradb-data/cache
printf '%s\n' 'local-development-token-32-bytes' > hydradb-data/auth-token
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -p 7687:7687 -p 8443:8443 -p 9090:9090 \
  -v "$PWD/hydradb-data:/data" \
  -e CLOUD_PROVIDER=local \
  -e LOCAL_PATH=/data/store \
  -e GRAPH_NAMESPACE=default \
  -e GRAPH_ID=default \
  -e GRAPH_CELL_ID=cell-0 \
  -e GRAPH_CELLS=cell-0 \
  -e GRAPH_NODE_ID=node-0 \
  -e GRAPH_BOLT_NODE_ADDRESSES=node-0=127.0.0.1:7687 \
  -e GRAPH_ADVERTISED_BOLT_ADDR=127.0.0.1:7687 \
  -e GRAPH_DATA_CACHE_DIR=/data/cache \
  -e GRAPH_AUTH_TOKEN_FILE=/data/auth-token \
  -e GRAPH_ALLOW_PLAINTEXT=true \
  -e RUST_MIN_STACK=33554432 \
  ghcr.io/hydra-db/hydradb:latest

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

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

git clone https://github.com/hydra-db/hydradb.git
cd hydradb
just native-check
just smoke

just minio-smoke

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"
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

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

Verify a running node

However you started it, the node listens on:

| Endpoint | Address | Purpose | |---|---|---| | Bolt | 127.0.0.1:7687 | Neo4j-driver-compatible queries | | HTTP | 127.0.0.1:8443 | JSON and NDJSON query API | | Admin | 127.0.0.1:9090 | readiness and Prometheus metrics |

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.

Agents working in this repository should read AGENTS.md, which carries the same sequence plus repository conventions and failure modes. Contributors building HydraDB should also read DEVELOPMENT.md for the full recipe, harness, and script surface.

Querying

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.

Native path procedures

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

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.

Read Consistency

HydraDB exposes two read modes:

| Mode | Behavior | |---|---| | causal | Uses the node's current durable reader view and refreshes when a supplied bookmark requires a newer sequence. This is the default hot path. | | strong | Refreshes the SlateDB reader from object storage before pinning the query snapshot. This pays the object-store freshness cost. |

HTTPS requests set "consistency": "causal" or "strong" in the request body. Bolt clients set consistency in RUN metadata or hydradb.consistency in transaction metadata.

Kubernetes

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 Helm chart guide for configuration and rollout details.

Observability

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. Read docs/runbooks/duration-histograms.md before building latency dashboards or alerts.

Development

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. DEVELOPMENT.md documents the complete surface — verification recipes, local and MinIO harnesses, and the standalone scripts. Run just ci before opening a pull request.

Repository layout

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
docs/               architecture notes, runbooks, benchmarks, and verification

Benchmarks

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.

Documentation

| Document | Contents | |---|---| | Architecture | End-to-end design, snapshots, writer ownership, query execution, and indexing | | Helm chart guide | Kubernetes configuration, TLS, authentication, upgrades, and verification | | Duration histograms | Correct latency units, PromQL, aggregation, and alerting | | Correctness casebook | Reproduced storage and query invariants with regression evidence | | Formal verification | Quint and model-based testing evidence | | Jepsen report | Distributed consistency test results |

Contributing

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.

License

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