Contributing to HelixDB

Overview

HelixDB is a high-performance graph-vector database built in Rust, optimized for RAG and AI applications. It combines graph traversals, vector similarity search, and full-text search in a single database.

We welcome contributions from the community! This guide will help you get started with contributing to HelixDB.

How to Contribute

Reporting Issues

Check existing GitHub Issues to avoid duplicates
Use a clear, descriptive title
Include steps to reproduce for bugs
Provide system information (OS, Rust version, HelixDB version)
Add relevant logs or error messages

Contribution Workflow

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/helix-db.git
cd helix-db

Create a feature branch from main:

git checkout -b feature/your-feature-name

Make your changes following our coding guidelines
Commit your changes with clear, descriptive commit messages:
```
git commit -m "feat: add new feature description"
```

Push to your fork:

git push origin feature/your-feature-name

Open a Pull Request against the main branch
Respond to feedback from reviewers

Pull Request Guidelines

Link related issues in the PR description
Ensure all tests pass
Add tests for new features
Update documentation if needed
Keep PRs focused on a single feature or fix
Write clear commit messages following conventional commits format

Prerequisites and Development Setup

Required Tools

Rust: 1.75.0 or later (install via rustup)
Cargo: Comes with Rust
Git: For version control

Optional Tools

cargo-watch: For development auto-reloading
cargo-nextest: Faster test runner
rust-analyzer: IDE support

Building the Project

Clone the repository:

git clone https://github.com/HelixDB/helix-db.git
cd helix-db

Build all components:
```
cargo build
```
Build in release mode (optimized):
```
cargo build --release
```

Building Specific Components

The Cargo workspace members are helix-cli, metrics, and sdks/rust:

CLI: cargo build -p helix-cli
Metrics: cargo build -p helix-metrics
Rust DSL SDK: cargo build -p helix-db (the SDK crate in sdks/rust; docs at docs.rs/helix-db)

The TypeScript SDK (sdks/typescript) and Go SDK (sdks/go) build with their own toolchains (npm, go).

Running HelixDB Locally

Install the CLI (development version):
```
cargo install --path helix-cli
```

Initialize a test project:

mkdir test-project && cd test-project
helix init

Start a local instance (Docker/Podman container):
```
helix start dev
```

Send a query:

helix query dev --file examples/request.json

Project Structure

This repository contains the user-facing tooling for HelixDB: the CLI, the client SDKs, and metrics. The database engine itself runs inside the enterprise-dev container image that the CLI pulls and manages — it is not built from this repo. The root holds helix-cli/, sdks/, metrics/, and assets/.

Core Components

`/helix-cli/` - Command-Line Interface

User-facing CLI for managing HelixDB instances and deployments.

Directory Structure:

helix-cli/
├── src/
│   ├── commands/           # CLI command implementations (one module per subcommand)
│   │   ├── logs/          # Local + Enterprise Cloud log viewing
│   │   ├── add.rs         # Add a local or Enterprise Cloud instance
│   │   ├── auth.rs        # Enterprise Cloud auth (login/logout/create-key)
│   │   ├── chef.rs        # Bootstrap a first Helix app for a coding agent
│   │   ├── config.rs      # workspace/project/cluster config (hidden parent)
│   │   ├── dashboard.rs   # Launch the Helix Dashboard
│   │   ├── delete.rs      # Delete an instance and its local state
│   │   ├── enterprise_deploy.rs # Enterprise Cloud deploy helpers
│   │   ├── feedback.rs    # Send feedback to the Helix team
│   │   ├── init.rs        # Initialize a v2 project
│   │   ├── metrics.rs     # Metrics configuration
│   │   ├── prune.rs       # Prune local containers/workspaces
│   │   ├── push.rs        # Deploy an Enterprise Cloud instance
│   │   ├── query.rs       # Send a dynamic query to POST /v1/query
│   │   ├── restart.rs     # Restart a background local instance
│   │   ├── start.rs       # Start a local instance (alias: run)
│   │   ├── status.rs      # Instance status
│   │   ├── stop.rs        # Stop a background local instance
│   │   ├── sync.rs        # Sync Enterprise Cloud metadata into helix.toml
│   │   └── update.rs      # Self-update the CLI
│   ├── config.rs          # helix.toml + ~/.helix config management
│   ├── enterprise_cloud.rs # Enterprise Cloud REST types and fetchers
│   ├── errors.rs          # Error handling
│   ├── lib.rs             # Library interface + subcommand enums
│   ├── local_runtime.rs   # Docker/Podman container lifecycle
│   ├── main.rs            # Entry point + clap command definitions
│   ├── metrics_sender.rs  # Metrics collection
│   ├── output.rs          # Terminal output / verbosity helpers
│   ├── port.rs            # Port availability helpers
│   ├── project.rs         # Project context + helix.toml discovery
│   ├── prompts.rs         # Interactive cliclack prompts
│   ├── setup.rs           # Shared init/chef setup helpers
│   ├── sse_client.rs      # Server-sent-event client (auth/deploy/logs)
│   ├── ts_query.rs        # TypeScript DSL query evaluation
│   ├── update.rs          # Self-update functionality
│   └── utils.rs           # Utilities

Available Commands:

helix init - Initialize a v2 Helix project
helix chef (alias cook) - Bootstrap a first Helix app for a coding agent
helix add - Add a local or Enterprise Cloud instance to a project
helix start (alias run) - Start a local instance in the background
helix stop - Stop a background local instance
helix restart - Restart a background local instance
helix status - Show local and Enterprise Cloud instance status
helix logs - View logs for a local or Enterprise Cloud instance
helix query - Send a dynamic query to POST /v1/query
helix push - Deploy an Enterprise Cloud instance
helix auth - Enterprise Cloud authentication (login/logout/create-key)
helix workspace - Manage the active Enterprise Cloud workspace
helix project - Manage the linked Enterprise Cloud project
helix cluster - List and inspect Enterprise Cloud clusters
helix sync - Sync Enterprise Cloud metadata into helix.toml
helix prune - Prune local containers/workspaces
helix delete - Delete an instance from helix.toml and local state
helix metrics - Configure metrics collection (full/basic/off/status)
helix dashboard - Launch the Helix Dashboard (start/stop/status)
helix update - Update the CLI to the latest version
helix feedback - Send feedback to the Helix team

Deployment Targets:

Local Docker/Podman containers (helix start) — image ghcr.io/helixdb/enterprise-dev
Helix Cloud (managed Enterprise hosting) via helix push

Build & Deploy Flow:

The v3 CLI is a runtime orchestrator — there is no helix compile/helix check step and no .hx query files.

Scaffold a project with helix init (writes helix.toml and a .helix/ workspace).
Start a local instance with helix start — a Docker/Podman container running the enterprise-dev image (in-memory by default, on-disk with --disk).
Author queries with the Rust, TypeScript, Go, or Python DSL; they serialize to JSON "dynamic queries".
Send queries to a running instance via POST /v1/query (helix query); validation happens server-side.
For production, deploy an Enterprise Cloud instance with helix push, managing auth/metadata via helix auth, helix sync, and the workspace/project/cluster commands.

Supporting Components

`/sdks/` - Client SDKs

Client libraries that build HelixDB queries and send them to a running instance.

rust/ - Rust DSL builder (crate helix-db), with the helix-dsl-macros procedural-macro crate
typescript/ - TypeScript DSL (@helix-db/helix-db)
go/ - Go client and DSL
python/ - Python client and DSL (helix-db, imported as helixdb)
tests/ - Cross-SDK parity tests and metadata registration tests

`/metrics/` - Metrics

The helix-metrics crate used by the CLI for telemetry collection.

`/assets/` - Brand Assets

Logos and images used in the README and docs.

Key Concepts

Query Language

Queries are authored with the Rust, TypeScript, Go, or Python DSL (in sdks/) and serialized to JSON "dynamic queries" sent to a running instance. The legacy HelixQL .hx form below is still supported for reference and translation:

QUERY addUser(name: String, age: I64) =>
   user <- AddN<User({name: name, age: age})
   RETURN user

Data Model

Nodes (N::) - Graph vertices with properties
Edges (E::) - Relationships between nodes
Vectors (V::) - High-dimensional embeddings

Operations

Graph traversals: In, Out, InE, OutE
Vector search: HNSW-based similarity search
Text search: BM25 full-text search
CRUD: AddN, AddE, Update, Drop

Architecture Flow

Definition: Author queries with a Rust, TypeScript, Go, or Python DSL
Serialization: The DSL produces a JSON dynamic-query AST (POST /v1/query body)
Execution: Send to a running instance with helix query; the gateway validates and runs it server-side
Storage: LMDB handles persistence with ACID guarantees

Development Guidelines

Code Style

Prefer functional patterns (pattern matching, iterators, closures)
Document code inline - no separate docs needed
Minimize dependencies
Use asserts liberally in production code

Linting

Run Clippy to check code quality:

./clippy_check.sh

The clippy_check.sh script at the repository root runs cargo clippy --workspace -- -D warnings, treating all warnings as errors across every workspace crate.

Testing

Tests live alongside the code in each crate and SDK:

Test Structure

CLI Tests (helix-cli)

Inline #[cfg(test)] modules throughout helix-cli/src/
clap argument-parsing tests in src/main.rs (every command/flag combo)
Config (de)serialization and backward-compat defaults in src/config.rs
chef prompt rendering, agent-priority, and stream-json parsing in src/commands/chef.rs

SDK Tests (sdks/)

sdks/rust/ - Rust DSL unit tests (cargo test -p helix-db)
sdks/typescript/ - TypeScript DSL tests (run with npm test)
sdks/go/ - Go DSL tests (go test ./...)
sdks/tests/ - Cross-SDK parity tests and metadata registration tests

Running Tests

# Run all Rust workspace tests
cargo test --workspace

# Run specific crate tests
cargo test -p helix-cli
cargo test -p helix-db      # Rust SDK in sdks/rust

# TypeScript SDK
cd sdks/typescript && npm test

# Go SDK
cd sdks/go && go test ./...

Format and lint before opening a PR: cargo fmt and ./clippy_check.sh.

Testing Guidelines

Write tests for all new features
Include both positive and negative test cases
Ensure tests pass locally before opening PR

Performance

Currently 1000x faster than Neo4j for graph operations
On par with Qdrant for vector search
LMDB provides memory-mapped performance

Communication Channels

Getting Help

Discord: Join our Discord community for real-time discussions, questions, and support
GitHub Issues: Report bugs or request features at github.com/HelixDB/helix-db/issues
Documentation: Check docs.helix-db.com for comprehensive guides
Twitter/X: Follow @helixdb for updates and announcements

Before You Ask

Search existing GitHub issues and Discord for similar questions
Check the documentation for relevant guides
Try to create a minimal reproducible example
Include error messages, logs, and system information

Community Guidelines

Be respectful and constructive
Help others when you can
Share your use cases and learnings
Follow our Code of Conduct

Code Review Process

What Reviewers Look For

Correctness: Does the code work as intended?
Tests: Are there adequate tests? Do they pass?
Code style: Does it follow Rust and HelixDB conventions?
Performance: Are there obvious performance issues?
Documentation: Are complex parts explained?
Scope: Is the PR focused on a single feature/fix?

Common Reasons PRs Get Rejected

Failing tests or CI checks
No tests for new functionality
Breaks existing functionality
Code style violations
Too broad in scope (mixing multiple unrelated changes)
Missing documentation for complex features
Performance regressions without justification

How to Respond to Feedback

Address all reviewer comments
Ask for clarification if feedback is unclear
Make requested changes in new commits (don't force push during review)
Mark conversations as resolved after addressing them
Be patient and respectful - reviewers are volunteers

Review Timeline

Initial response: Usually within 2-3 days
Follow-up reviews: 1-2 days after updates
Complex PRs may take longer
Feel free to ping on Discord if your PR hasn't been reviewed after a week

Getting Started

Install CLI: curl -sSL "https://install.helix-db.com" | bash
Initialize project: helix init --path <path>
Start a local instance: helix start dev
Author queries with the Rust or TypeScript DSL (see sdks/)
Send a query: helix query dev --file examples/request.json

License

AGPL (Affero General Public License)

For commercial support: founders@helix-db.com

Uh oh!