ClickHouse is a great database and a poor API. WaveHouse is the API.

The open-source real-time API gateway for ClickHouse — schema-aware ingest, async batching, real-time SSE streaming, and tiered query caching 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 -d   # ClickHouse + WaveHouse (ships a dev policy)

# create a table (Bring Your Own 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"

# stream live events in one terminal, then ingest one in another and watch it arrive
curl -N "http://localhost:8080/v1/stream?table=events" & sleep 1
# in another terminal, ingest an event (no auth needed with the dev policy)
# (a 404 "unknown table" here just means schema discovery hasn't seen the new table yet — retry; worst case 60s)
curl -sX POST "http://localhost:8080/v1/ingest?table=events" \
  -H 'content-type: application/json' -d '{"kind":"click","user":"u_42"}'

Full walkthrough → wavehouse.dev/getting-started.

ClickHouse is a phenomenal OLAP database, but pointing a frontend straight at it has sharp edges: 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 OK instantly, background batch-flush; schema-validated against system.columns; optional ID-based dedup (idempotent ingest); dead-letter queue for failed inserts.
• Query — in-process Ristretto cache + singleflight coalescing; 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: zero-dependency TypeScript client with query builder, live queries, streaming, and schema codegen.

Full breakdown, failure modes, and the engineering rationale → wavehouse.dev/why-wavehouse.

Pick whichever fits — each ends with WaveHouse listening on http://localhost:8080.

git clone https://github.com/Wave-RF/WaveHouse.git && cd WaveHouse
docker compose -f deployments/compose/standalone.yaml up -d

The stack ships a permissive dev policy, so you can ingest without a token. Create a table in ClickHouse (Bring Your Own Schema), then ingest — see the getting-started walkthrough for the full ingest → query → stream tour.

docker pull ghcr.io/wave-rf/wavehouse:latest    # tagged release
docker pull ghcr.io/wave-rf/wavehouse:dev       # rolling main-branch build

Both tags carry a signed Sigstore build-provenance attestation — verify before you deploy:

gh attestation verify oci://ghcr.io/wave-rf/wavehouse:latest --repo Wave-RF/WaveHouse

go install github.com/Wave-RF/WaveHouse/cmd/wavehouse@latest

You'll still need ClickHouse reachable — point WaveHouse at it via WH_CH_ADDR (defaults to localhost:9000). See Configuration.

WaveHouse is in alpha — built in the open, Apache-2.0-licensed, no vendor lock-in. 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+. 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 save

AI-assisted, human-reviewed. Much of WaveHouse — code and docs alike — is written with AI assistance (Claude Code). Every change, whether AI- or human-authored, goes through the same review gates, tests, and CI before it lands. We note it for transparency: treat the docs as the source of truth, and please open an issue if anything reads as off or out of date.

The repo ships minimal team-wide Claude Code configuration — safety guardrails, a couple of slash commands / subagents, an auto-format hook, 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.

Issues, 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? Don't 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.

WaveHouse is open source under the Apache License 2.0.