HyperbyteDB Documentation¶
Welcome to the HyperbyteDB documentation. HyperbyteDB is a time-series database written in Rust that provides InfluxDB v1 API compatibility, uses embedded ClickHouse (chDB) for queries, Apache Parquet for storage, and RocksDB for the write-ahead log and metadata. It supports master-master clustering with Raft-based schema consensus.
How to Navigate¶
This documentation is organized into two main sections based on audience, plus a shared glossary.
User Guide — For operators and end-users¶
Everything you need to deploy, configure, and operate HyperbyteDB in production. No source-code knowledge required. The user guide index lists a recommended reading order (install → configure → basic usage → optional topics). Core pages live under user-guide/; the Kubernetes operator docs are in user-guide/operator/.
| Topic | Description |
|---|---|
| Installation | Docker, pre-built images, building from source |
| Configuration | Config file sections, environment variables, example files |
| Authentication | Enabling auth, credentials, public vs protected routes, admin for internal APIs |
| Basic operations | First database, writes, queries, retention |
| Advanced features | Clustering, continuous queries, TLS, S3 |
| Common workflows | InfluxDB migration, Telegraf, Grafana |
| Administration | Monitoring, backup/restore, compaction, cluster operations |
| Troubleshooting | Common problems and solutions |
| API & InfluxQL Reference | HTTP endpoints, InfluxQL syntax, compatibility matrix |
| Kubernetes operator | Helm, HyperbytedbCluster CRD, backups, hyperbytedb-proxy |
Developer Guide — For contributors and engineers¶
Technical details for anyone reading, modifying, or extending the HyperbyteDB codebase.
| Topic | Description |
|---|---|
| Architecture | Hexagonal design, data flow diagrams, component overview |
| System architecture | Long-form internal design (modules, paths, storage, services) |
| Replication design | /internal/replicate wire format, sync_quorum, hinted handoff |
| Development Setup | Local environment, dependencies, building, running |
| Core Modules | Module-by-module source guide |
| Key Design Decisions | Write path, read path, compaction, replication internals |
| Extension Points | Adding statements, storage backends, background services |
| Coding Standards | Conventions, patterns, error handling, async rules |
| Testing | Test suites, running tests, writing new tests |
| Building & CI | CI pipeline, Docker builds, release process |
| Contributing | PR process, code review rubric, engineering policies |
Glossary¶
Shared terminology used across both guides.
Deep dives — Subsystem walkthroughs¶
Detailed write path, read path, compaction, self-repair, and clustering docs with pointers to source files.
Quick Links¶
- 30-second start:
docker compose up --build -d— see Installation - Write data:
curl -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'cpu,host=srv01 value=42' - Query data:
curl -G 'http://localhost:8086/query' --data-urlencode 'db=mydb' --data-urlencode 'q=SELECT * FROM cpu' - Configuration reference: user-guide/configuration.md
- Benchmarks (Criterion + HTTP soak): benchmarks.md
- GitHub Container Registry image:
ghcr.io/hyperbyte-cloud/hyperbytedb:latest