WaveHouse

WaveHouse is an open-source, Apache 2.0-licensed API gateway built by Wave RF that sits between your frontend and ClickHouse, solving the sharp edges of pointing applications directly at the OLAP database. It ships as a single binary with no external dependencies beyond ClickHouse itself, and is currently in alpha with active development tracked on a public GitHub project board.

What It Is

WaveHouse is a real-time API gateway purpose-built for ClickHouse. The project describes itself as "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." It consolidates what would otherwise be a custom API layer, a Kafka queue, a batch consumer, a cache tier, and an auth service into one deployable Go binary.

Core Architecture

The single wavehouse process bundles several subsystems in-process:

• Async WAL ingest — writes land in an embedded NATS JetStream write-ahead log and return 200 OK instantly; a background worker batch-flushes to ClickHouse, eliminating "too many parts" errors under load.
• Schema-aware validation — WaveHouse discovers table schemas via ClickHouse's system.columns and rejects unknown fields, type mismatches, and null violations at the edge before they reach the database.
• Real-time SSE streaming — events are broadcast to Server-Sent Events subscribers before the ClickHouse flush, with JetStream gap-fill for late-connecting or reconnecting clients.
• In-process query cache — Ristretto cache plus Go singleflight coalesces identical concurrent queries, protecting dashboards from thundering-herd scenarios without an additional cache tier.
• Hasura-style access control — per-table, per-role column and row-level policies with JWT claim templating, stored in NATS KV with file-based bootstrap and cluster sync.
• Optional deduplication — idempotent ingest by ID using an embedded Pebble store, plus a dead-letter queue for failed batch inserts.

TypeScript SDK and Named Pipes

The @wavehouse/sdk npm package provides a type-safe query builder, live queries, real-time streaming, and schema codegen. The homepage notes it has one runtime dependency (an SSE frame parser) at approximately 1.4 KB gzipped. The SDK exposes a chainable .from().select().where().orderBy().limit() API that never throws — results branch on { data, error }. Live queries backfill history before opening the stream, and can be closed explicitly. The gateway also supports Tinybird-style named pipes: parameterized SQL endpoints with parameter binding and per-role restrictions.

Setup Path

The project ships a Docker Compose file that starts WaveHouse and ClickHouse together. The homepage describes the path from git clone to a live event stream as five minutes. Three installation options are documented: Docker Compose (recommended), a prebuilt container image from GitHub Container Registry (with Sigstore build-provenance attestation), and go install for a bare binary. The only external runtime dependency is a reachable ClickHouse instance. Local development requires Go 1.26+, GNU Make 4+, Docker Compose v2, Node.js 22 LTS, and pnpm 11.21+.

Current Status: Alpha

WaveHouse is explicitly alpha and pre-1.0. The project documentation states that APIs, configuration, wire formats, and on-disk state can change between releases without a migration path. The support cadence is best-effort at 1–2 business days. A managed cloud offering, WaveHouse Cloud, is available at wavehouse.cloud and runs the same Apache 2.0 binary operated by the project authors, with managed ClickHouse, autoscaling, and usage-based billing — moving between self-hosted and managed is described as a config change, not a migration. The latest SDK release is @wavehouse/sdk 0.1.1, published in August 2026.