Development Setup¶

Set up a local environment for building, running, and debugging HyperbyteDB. For production deployment paths (Docker, Compose, Kubernetes operator), see Installation.

Prerequisites¶

Install everything in one step:

sh scripts/install-dev-deps.sh

Or install manually:

Rust¶

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

System dependencies¶

# Debian/Ubuntu (amd64 and arm64)
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

# macOS (Homebrew) — Apple Silicon and Intel
brew install llvm pkg-config openssl@3
export LIBCLANG_PATH="$(brew --prefix llvm)/lib"

libchdb¶

curl -sL https://lib.chdb.io | bash
sudo ldconfig 2>/dev/null || true

The installer auto-detects your platform (Linux x86_64/aarch64, macOS x86_64/arm64) and places libchdb.so in /usr/local/lib/ and chdb.h in /usr/local/include/.

macOS note: the chdb installer writes libchdb.so even on macOS (not .dylib). The Rust crate links against it by name — leave the file as-is. If the binary fails at runtime with libchdb.so: cannot open shared object file, ensure /usr/local/lib is on DYLD_LIBRARY_PATH.

Verify:

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

If the build links but the binary cannot load libchdb.so at runtime on Linux, add /usr/local/lib to the linker path and run ldconfig again. See Troubleshooting.

Building¶

# Debug (faster compile)
cargo build

# Release (production-like)
cargo build --release

# Server only
cargo build --release -p hyperbytedb

# CLI client
cargo build --release -p hyperbytedb-cli

# Columnar MessagePack ingest is enabled by default; disable with:
cargo build --no-default-features

Debug builds optimize dependency crates at level 2 via [profile.dev.package."*"], which keeps chDB and RocksDB usable during development.

The release profile uses LTO, single codegen unit, and strip for maximum performance and minimum binary size.

Running¶

# Debug with default config
cargo run -- serve

# Custom config
cargo run -- -c /path/to/config.toml serve

# Release binary
./target/release/hyperbytedb serve

Server CLI commands¶

Quick smoke test:

curl -s http://localhost:8086/health
curl -sS -XPOST 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE dev'
curl -sS -XPOST 'http://localhost:8086/write?db=dev' --data-binary 'test,env=dev value=42'
# Wait ~10s for flush, then:
curl -sS -G 'http://localhost:8086/query' \
  --data-urlencode 'db=dev' --data-urlencode 'q=SELECT * FROM test'

Docker Compose (local build)¶

The root docker-compose.yml builds HyperbyteDB from source and starts the full observability stack (Alloy log shipping, Tempo tracing, etc.):

docker compose up --build -d

docker compose logs -f hyperbytedb

For a pre-built image stack without compiling, use the getting-started Compose file instead.

kind (local Kubernetes)¶

The deploy/kind/ directory contains a setup script and manifests for a local Kubernetes cluster:

./deploy/kind/setup.sh

This creates a kind cluster with:

• HyperbyteDB operator and a multi-node HyperbytedbCluster CR
• Observability stack (Prometheus, Grafana, Loki, Telegraf)
• NodePort services mapped to localhost ports

Use this to develop and test operator changes without a cloud cluster. Production Kubernetes deployment is documented in Operator installation.

Project layout¶

hyperbytedb/
├── Cargo.toml              # Dependencies, features, profiles
├── config.toml.example     # Example server configuration
├── Dockerfile              # Multi-stage image build
├── docker-compose.yml      # HyperbyteDB + observability stack (local build)
├── deploy/
│   ├── compose/            # Prometheus, Grafana, Loki, Tempo, Alloy, Telegraf
│   └── kind/               # Local Kubernetes dev cluster
├── src/
│   ├── main.rs             # CLI entry point
│   ├── bootstrap.rs        # Composition root
│   ├── domain/             # Domain types
│   ├── ports/              # Trait definitions
│   ├── adapters/           # RocksDB, chDB, HTTP, cluster
│   ├── application/        # Business logic services
│   └── timeseriesql/       # TimeseriesQL parser and translator
├── tests/
│   ├── integration.rs      # Auth, metrics, backup, layout
│   ├── raft_integration.rs # Multi-node cluster
│   ├── sync_quorum_integration.rs
│   └── compat/             # InfluxDB v1 compatibility
├── scripts/                # load.sh, install-dev-deps.sh, benchmarks
└── docs/                   # Documentation (MkDocs)

Environment variables¶

Override any config setting:

HYPERBYTEDB__LOGGING__LEVEL=debug cargo run -- serve

Fine-grained tracing filters:

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

Common commands¶

Build the published docs site locally:

pip install -r docs/requirements.txt
mkdocs serve

See also¶

• Installation — Customer deployment paths
• Architecture
• Testing
• Building & CI