ClickHouse® is a great database with a subpar API. WaveHouse fixes that.
The open-source real-time API gateway for ClickHouse: schema-aware ingest, async batching, real-time SSE streaming, and tiered query caching. All in a single binary.
Docs · Quick start · Why WaveHouse · Discussions
git clone https://github.com/Wave-RF/WaveHouse.git && cd WaveHouse
docker compose -f deployments/compose/standalone.yaml up -dThe in-repo compose spins up WaveHouse and ClickHouse. Then, create a table (or import your existing schema):
docker compose -f deployments/compose/standalone.yaml exec clickhouse \
clickhouse-client --query "CREATE TABLE IF NOT EXISTS events (kind String, user String, received_timestamp DateTime64(3,'UTC') DEFAULT now64(3,'UTC')) ENGINE=MergeTree ORDER BY kind"Then, stream live events in one terminal, ingest one in another, and watch the ingested events arrive from the stream:
curl -N "http://localhost:8080/v1/stream?table=events" & sleep 1Important
No auth is needed to ingest with the default dev policy. The policy is VERY permissive, and not intended for production deployments.
curl -sX POST "http://localhost:8080/v1/ingest?table=events" \
-H 'content-type: application/json' -d '{"kind":"click","user":"u_42"}'Tip
A 404 "unknown table" error here just means schema discovery hasn't seen the new table yet. Just retry; worst case 60s before discovery.
Full walkthrough at wavehouse.dev/getting-started.
ClickHouse is a phenomenal OLAP database, but pointing a frontend right at it leaves a lot to be desired: one-row inserts trigger Too many parts, there's no backpressure or edge validation, no real-time push, and no row/column security. You end up building custom APIs, a Kafka queue, a batch consumer, a cache tier, and an auth service. WaveHouse is that whole stack as one binary — the only external dependency is ClickHouse.
If you're building user-facing analytics, WaveHouse is like Supabase for ClickHouse. Or an open-source Tinybird that pushes data to the frontend in real time over SSE, not just pull-based REST.
- Ingest — async durable WAL (embedded NATS JetStream),
200 OKinstantly, background batch-flush; schema-validated againstsystem.columns; optional ID-based dedup (idempotent ingest); dead-letter queue for failed inserts. - Query — in-process Ristretto cache +
singleflightcoalescing; type-safe structured query AST; Tinybird-style named pipes (parameterized SQL endpoints). - Real-time — native SSE push, broadcast before the ClickHouse flush, with JetStream gap-fill for late/reconnecting clients.
- Security — Hasura-style per-table, per-role column + row policies with JWT claim templating, stored in NATS KV.
- Client —
@wavehouse/sdk: TypeScript client with query builder, live queries, streaming, and schema codegen; one runtime dependency (an SSE frame parser, ~1.4 KB gzipped).
| Direct ClickHouse | Kafka + CH (DIY) | Tinybird | WaveHouse | |
|---|---|---|---|---|
| Self-hosted, single binary | — | — | ✗ (SaaS) | ✓ |
| Safe high-rate inserts | ✗ | ✓ (via Kafka) | ✓ | ✓ |
| Schema validation at the edge | ✗ | custom | ✓ | ✓ |
| Real-time push (SSE) | ✗ | custom service | ✗ | ✓ native |
| Thundering-herd coalescing | ✗ | custom | ✓ | ✓ |
| Row/column policies (JWT) | ✗ | custom | tokens only | ✓ Hasura-style |
| Cost model | infra | infra + eng time | per-vCPU SaaS | infra only |
Full breakdown, failure modes, and our engineering rationale at wavehouse.dev/why-wavehouse.
Pick between the in-repo Docker Compose, pulling a container image, or go install. The Compose option starts WaveHouse; the other options just download/install a container or binary. Run the selected artifact before using http://localhost:8080.
git clone https://github.com/Wave-RF/WaveHouse.git && cd WaveHouse
docker compose -f deployments/compose/standalone.yaml up -dThe stack has a permissive dev policy, so you can ingest without a token. Create a table in ClickHouse (or import existing schema), then ingest — see the getting-started walkthrough for the full ingest → query → stream tour.
docker pull ghcr.io/wave-rf/wavehouse:latest # latest stable release
docker pull ghcr.io/wave-rf/wavehouse:dev # rolling main-branch buildTags carry a signed Sigstore build-provenance attestation — verify before you deploy:
gh attestation verify oci://ghcr.io/wave-rf/wavehouse:dev \
--repo Wave-RF/WaveHouse \
--signer-workflow Wave-RF/WaveHouse/.github/workflows/publish-dev.ymlSwap in :vX.Y.Z and release.yml for a release image. Pin the signer either way. --repo alone accepts an attestation from any workflow in the repo.
go install github.com/Wave-RF/WaveHouse/cmd/wavehouse@latestYou'll still need ClickHouse reachable. Point WaveHouse at it by setting WH_CH_ADDR (defaults to localhost:9000). See Configuration for more information.
WaveHouse is in alpha. See SUPPORT.md for where to ask what, the alpha-stage response cadence (best-effort, 1–2 business days), and what's in vs. out of scope right now.
Track what's shipped, in progress, and planned on the project board.
Alpha = expect change. WaveHouse is pre-1.0: APIs, configuration, wire formats, and on-disk state can change between releases without a migration path, and some capabilities are still hardening. Pin a version and don't rely on stability guarantees until a tagged GA release.
You'll need Go 1.26+, GNU Make 4+, Docker (Compose v2), Node.js 22 LTS, and pnpm 11.21+. See development docs for the authoritative source of truth with the full list, version requirements, and gotchas.
make tools # one-time bootstrap
docker compose -f deployments/compose/dependencies.yaml up -d clickhouse
make dev # hot-reload on .go saveIssues, pull requests, and feedback welcome! See our CONTRIBUTING.md guidelines on how to structure your code and run the integration test suites.
Found a vulnerability? Do NOT open a public issue. Email security@wave-rf.com per SECURITY.md — we acknowledge within 48 hours and aim for an initial assessment in 5 business days.
The repo contains a minimal Claude Code configuration: safety guardrails, a couple of slash commands and subagents, auto-format hooks, and worktrunk project hooks for parallel agent workflows. Personal preferences (status line, model, allow lists) stay user-level. See Claude Code & AI agents for setup + reference. AGENTS.md at the repo root is the canonical source of truth for project conventions.
AI-assisted, human-reviewed. WaveHouse has been developed with AI assistance (Claude Code). Every change, whether AI- or human-authored, goes through the same review gates, tests, and CI before it gets merged. The docs are the source of truth, and please open an issue if anything is out of date. (or, obviously, if you notice an issue that isn't security-related)
WaveHouse is open source under the Apache License 2.0.