# WaveHouse

> Open-source real-time API gateway for ClickHouse with schema-aware ingest, async batching, SSE streaming, and tiered query caching in a single binary.

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.

## Features
- Schema-aware ingest validated against ClickHouse system.columns
- Async WAL with embedded NATS JetStream and batch flush
- Real-time SSE streaming with JetStream gap-fill for late clients
- In-process Ristretto query cache with singleflight coalescing
- Hasura-style per-table per-role JWT row/column access policies
- Optional ID-based deduplication with embedded Pebble store
- Dead-letter queue for failed batch inserts
- Tinybird-style named pipes with parameter binding and per-role restrictions
- TypeScript SDK with type-safe query builder, live queries, and schema codegen
- Single binary deployment with embedded NATS JetStream
- Docker Compose quickstart
- Sigstore build-provenance attestation on container images
- Hot-reload settings directory at boot and runtime
- Go client SDK with full API-tree parity

## Integrations
ClickHouse, NATS JetStream, Docker, Docker Compose, JWT/JWKS, Pebble (embedded key-value store), Ristretto (in-process cache), GitHub Container Registry, Sigstore

## Platforms
LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
clients/ts/v0.1.1

## Links
- Website: https://wavehouse.dev
- Documentation: https://wavehouse.dev/getting-started
- Repository: https://github.com/Wave-RF/WaveHouse
- EveryDev.ai: https://www.everydev.ai/tools/wavehouse