Development Setup¶

How to set up a local development environment for building, running, and debugging HyperbyteDB.

Prerequisites¶

Requirement	Details
Rust	Latest stable toolchain
libchdb	Embedded ClickHouse library (Linux x86_64)
System packages	`clang`, `llvm-dev`, `libclang-dev`, `pkg-config`, `libssl-dev`
Docker	Optional, for integration tests and full-stack runs
Go	Optional, for running `tests/e2e/` end-to-end tests

Install Rust¶

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env
rustup update stable

Install system dependencies¶

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y --no-install-recommends \
  clang llvm-dev libclang-dev pkg-config libssl-dev build-essential

# Fedora/RHEL
sudo dnf install -y clang llvm-devel clang-devel pkgconfig openssl-devel

Install libchdb¶

curl -sL https://lib.chdb.io | bash
sudo ldconfig

Verify:

ls /usr/local/lib/libchdb.so
ls /usr/local/include/chdb.h

Building¶

Debug build¶

cargo build

Debug builds are faster to compile but significantly slower at runtime. Dependency crates are optimized at level 2 via the [profile.dev.package."*"] setting, which helps with chDB and RocksDB performance even in debug mode.

Release build¶

cargo build --release

The release profile uses LTO (fat), single codegen unit, panic = "abort", and stripping for maximum performance and minimum binary size.

Additional binaries¶

# Debug CLI for cluster inspection
cargo build --bin hyperbytedb-debug

# InfluxDB 1.x migration tool
cargo build --bin hyperbytedb-backfill

Optional features¶

# Build with columnar MessagePack ingest support
cargo build --features columnar-ingest

Running¶

Start the server¶

# Debug mode with default config
cargo run -- serve

# Debug mode with custom config
cargo run -- -c /path/to/config.toml serve

# Release binary
./target/release/hyperbytedb serve

Quick verification¶

# Check health
curl -s http://localhost:8086/health

# Create a database
curl -sS -XPOST 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE dev'

# Write test data
curl -sS -XPOST 'http://localhost:8086/write?db=dev' \
  --data-binary 'test,env=dev value=42'

# Query (wait ~10s for flush)
curl -sS -G 'http://localhost:8086/query' \
  --data-urlencode 'db=dev' --data-urlencode 'q=SELECT * FROM test'

Docker Compose (full stack)¶

# Single node with Telegraf, Prometheus, Grafana
docker compose up --build -d

# View logs
docker compose logs -f hyperbytedb

Project Layout¶

hyperbyte-db/
├── Cargo.toml              # Crate metadata, dependencies, features, profiles
├── Cargo.lock              # Locked dependency versions
├── config.toml.example     # Example server configuration
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Full-stack compose (HyperbyteDB + monitoring)
├── .github/workflows/      # CI (ci.yml) and container (container.yml) pipelines
├── src/                    # Rust source code (see Core Modules)
│   ├── main.rs             # CLI entry point
│   ├── lib.rs              # Library root
│   ├── bootstrap.rs        # Composition root
│   ├── config.rs           # Configuration loading
│   ├── error.rs            # Error types
│   ├── domain/             # Pure domain types
│   ├── ports/              # Trait definitions
│   ├── adapters/           # Concrete implementations
│   ├── application/        # Business logic services
│   ├── influxql/           # Parser, AST, translator
│   ├── cluster/            # Clustering subsystem
│   └── bin/                # Additional binaries
├── tests/                  # Integration and compatibility tests
│   ├── integration.rs      # Basic integration tests
│   ├── raft_integration.rs # Raft-specific tests
│   ├── compat/             # InfluxDB v1 compatibility suite
│   └── e2e/                # Go end-to-end cluster tests
├── benches/                # Criterion benchmarks
├── examples/               # Example programs
├── scripts/                # Benchmark and test scripts
├── deploy/                 # Deployment configs (Prometheus, Telegraf, Grafana, kind)
└── docs/                   # This documentation

Environment Variables¶

For development, you can override any config setting via environment variables:

HYPERBYTEDB__LOGGING__LEVEL=debug cargo run -- serve

The RUST_LOG environment variable also works for fine-grained tracing control:

RUST_LOG=hyperbytedb=debug,tower_http=debug cargo run -- serve

Useful Development Commands¶

Task	Command
Check compilation	`cargo check`
Format code	`cargo fmt`
Run linter	`cargo clippy --all-targets -- -D warnings`
Run unit tests	`cargo test --lib`
Run integration tests	`cargo test --test '*'`
Run all tests	`cargo test`
Run benchmarks	`cargo bench`
Generate docs	`cargo doc --open`
Clean build artifacts	`cargo clean`