The runnable companion to the Coursera course HelixDB From Zero, course #20 in the Rust for Data Engineering specialization.

This repo ships a Helix schema + queries (db/schema.hx, db/queries.hx), a small helix-core Rust crate that wraps the official helix-rs SDK, and four named runtime contracts (C1–C4) that the demo binary asserts against a live instance.

Prerequisites:

• Docker (Compose v2 not required — helix-cli drives Docker directly)
• Rust 1.95+ (rust-toolchain.toml pins automatically)
• helix-cli (make install installs it via cargo install --git)

git clone https://github.com/paiml/helixdb-from-zero
cd helixdb-from-zero
make install   # cargo install helix-cli (idempotent — no-op if already present)

make up        # helix push dev — builds + starts HelixDB on 127.0.0.1:6969
make demo      # cargo run --bin helix-demo — runs all 4 contracts live
make down      # helix stop dev when you're done

make up is helix push dev under the hood: it compiles db/queries.hx, builds a Docker image, and starts the container. make demo then exercises the four contracts end-to-end and prints which assertion each one checked.

crates/helix-core/   Rust client + 4 named runtime contracts
contracts/           helix-rust-v1.yaml — formal spec for the four contracts
db/                  schema.hx + queries.hx — pushed by `helix push`
helix.toml           Helix project config (name, queries path, ports)
Makefile             entry points: install / up / demo / test / coverage / pmat / fmt / lint
assets/              hero.svg + hero.png

Each public async function in crates/helix-core/src/lib.rs asserts a named runtime contract immediately after the HTTP round trip. Formal spec lives in contracts/helix-rust-v1.yaml.

A breach panics with the contract name in the message; the demo binary walks all four against the running HelixDB and aborts loudly on any violation rather than ship corrupt state downstream.

HelixDB has no published Docker Hub image and no Homebrew tap; the canonical installer is cargo install --git https://github.com/HelixDB/helix-db helix-cli, which puts the helix binary on PATH. helix push <instance> then compiles the local .hx files, builds a Docker image on demand, and starts the container. This repo's make up / make down / make nuke wrap those commands directly — there is intentionally no compose.yml, since helix push is the deployment primitive.

make install    # cargo install helix-cli (one-time, idempotent)
make up         # helix push dev (HelixDB on 127.0.0.1:6969)
make demo       # cargo run --bin helix-demo (4 contracts, live engine)
make test       # cargo test --release (3 lib unit tests)
make coverage   # cargo llvm-cov --release --workspace
make lint       # cargo clippy --all-targets -- -D warnings
make fmt        # cargo fmt --all
make pmat       # pmat quality-gate
make down       # helix stop dev (preserves the volume)
make nuke       # helix delete dev (wipes graph + vector index)

PRs are welcome. Branch protection on main requires green CI (cargo fmt --check, cargo clippy -D warnings, cargo test, cargo build). Branch naming follows feat/<topic> / fix/<topic> / chore/<topic>. Open a PR against main; squash merge is the default.

Local pre-push checklist:

make fmt && make lint && make test

If you're touching db/schema.hx or db/queries.hx, also run make up && make demo to confirm the four contracts still assert against a real helix push dev instance — the unit tests do not cover the live HTTP path.

This repo is the companion to the Coursera course HelixDB From Zero, part of the Rust for Data Engineering specialization. Lessons walk through the four contracts as a path through HelixDB's primitives (vertices, edges, vectors, idempotent upsert) and the shape of building a small Rust service that talks to a graph-vector backend.

AGPL-3.0. HelixDB and its Rust SDK (helix-rs) are both AGPL-3.0, and helix-core links against helix-rs for HTTP transport

• typed query serialization. The combined work is therefore AGPL-3.0; the repo is licensed accordingly so the propagation is honest rather than implicit. If you fork this companion code without HelixDB itself (unlikely — the contracts are pointless without an engine), the AGPL obligations still attach via the SDK dependency.