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 traversal indexes live in S3-compatible storage. Independent compute. Data 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. Architecture flowchart TB C["Applications<br/>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<br/>WAL, SSTs, leases, CSC generations"] C --> SVC SVC --> N1 SVC --> N2 N1 <--> STORE N2 <--> STORE IX1 <--> STORE IXN <--> STORE Loading 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. Run with Docker — fastest, no local toolchain Release images are published to ghcr.io/hydra-db/hydradb . Each v* release is tagged with its full version, compatible minor and major versions, the commit SHA, and latest (for example 0.1.0 , 0.1 , 0 , latest , sha-7bf77ac ): docker pull ghcr.io/hydra-db/hydradb:latest Images are published for linux/amd64 and linux/arm64 , so Docker selects the right one for the host and Apple Silicon needs no extra flags. Releases up to and including 0.1.0 were linux/amd64 only, and pulling one of those on an ARM host fails with: no matching manifest for linux/arm64/v8 in the manifest list entries That message means the tag predates multi-architecture publishing, not that the pull is misconfigured. Move to a release after 0.1.0 , or run the older tag under emulation with --platform linux/amd64 — correct but slower, and it requires Rosetta on Apple Silicon. To see which architectures a tag actually carries before pulling it: docker buildx imagetools inspect ghcr.io/hydra-db/hydradb:latest This starts one plaintext node backed by a host directory mounted into the container: 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 The node runs in the foreground. LOCAL_PATH must point at a directory that already exists, which is why hydradb-data/store is created before the mount. --user "$(id -u):$(id -g)" is required: the image runs as UID/GID 10001 , but the bind-mounted hydradb-data is owned by the host user, so without it the container cannot write its store or cache and fails on the first storage operation. Running as the host user makes the mounted directories writable and keeps the created files host-owned. The image entrypoint is graph-node ; it also ships graph-indexer . For production, pin an image digest rather than latest — see the Helm chart guide . Build from source — for development and the full recipe surface Prerequisites 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. Clone and verify 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.