ClickHouse Hono
Build ClickHouse analytics APIs with Hono and hypequery
Hono is a fast, lightweight web framework that runs on Node.js, Cloudflare Workers, Deno, and Bun. hypequery gives Hono routes a typed ClickHouse data layer. The combination means you can build analytics APIs where the response shape is inferred all the way from the ClickHouse column definition to the browser client.
Framework
Hono
Runtime
Node.js, Edge, Bun, Deno
Best for
Fetch-based analytics APIs
Hono has no built-in ClickHouse integration — raw queries lose types immediately
Hono is deliberately data-layer agnostic. When you reach for @clickhouse/client inside a Hono route, you get untyped query results. You're back to casting responses or writing manual interfaces that drift from the actual ClickHouse schema.
Edge runtimes have different ClickHouse connection requirements than Node.js
Cloudflare Workers and other edge runtimes do not support persistent TCP connections. ClickHouse connections need to go over HTTP, and the client configuration differs from a standard Node.js setup. Getting this wrong silently is easy.
Hono's typed RPC client is wasted if ClickHouse responses are untyped any
Hono's hc() client propagates response types from your route handlers to the call site. But that only works if the route handler actually returns a typed value. If your ClickHouse query returns any, the type chain breaks and hc() provides no benefit.
How it fits together
hypequery gives Hono routes a typed ClickHouse return value
hypequery query builder methods return types inferred from your ClickHouse schema. When you call the query builder inside a Hono route handler and return c.json({ data: rows }), Hono infers the response shape from the rows type. The hc() RPC client gets the correct type automatically — no manual annotation on the route.
- Generate schema.ts with npx @hypequery/cli generate against your ClickHouse instance
- Call the hypequery query builder inside Hono route handlers
- Use zValidator from @hono/zod-validator for input validation — same pattern as hypequery input schemas
- Return c.json({ data: rows }) — Hono infers the response type from rows
- Use hc<AppType>() on the client to get fully typed responses from your ClickHouse analytics routes
Hono route
Typed ClickHouse analytics route in Hono
Auth middleware sets tenantId on the Hono context. The route handler reads it and passes it directly to the ClickHouse WHERE clause via the query builder.
Hono RPC pattern
End-to-end typed analytics with Hono RPC and hypequery
Hono's typed RPC system requires that route handlers return typed values. hypequery satisfies that requirement by inferring column types from your schema — so the hc() client on the browser side gets the correct shape for every ClickHouse response without any manual type definition.
This pattern translates cleanly between Node.js and fetch-based runtimes. The hypequery query builder uses ClickHouse over HTTP, which fits the deployment model Hono is commonly used for.
If you need interactive API documentation alongside the Hono routes, pair this with @hypequery/serve. The serve() function generates an OpenAPI spec and Swagger UI from your query definitions without requiring manual annotation.
Full stack example
Hono app with typed RPC and ClickHouse data layer
The AppType export carries route types to the client. The hc() call gets back typed data — { day: string; users: string }[] — without any manual interface on the client side.
Where teams usually get stuck
Questions teams ask
ClickHouse Hono TypeScript
Hono solves routing cleanly. The missing piece is a ClickHouse query layer that returns typed rows so route handlers and clients are not glued together with manual interfaces.
Hono analytics API ClickHouse
A Hono analytics API still needs validated inputs, predictable query results, and middleware-driven auth context. hypequery handles the ClickHouse part while Hono stays in charge of the HTTP layer.
ClickHouse edge runtime TypeScript
Fetch-based runtimes change the deployment shape more than the query shape. ClickHouse over HTTP fits that model, so the same core query definitions can move between Node and worker-style runtimes.
Hono RPC typed analytics
Hono's hc() client is most useful when the handler already returns a typed value. Schema-generated query results give Hono something concrete to propagate to the client.
Further reading
Go deeper where it actually helps
ClickHouse REST API
The general REST API guide — covers @hypequery/serve as a standalone HTTP server.
Open guide
ClickHouse OpenAPI
Auto-generated OpenAPI specs from hypequery query definitions.
Open guide
ClickHouse TypeScript
Schema generation and the typed query builder — the foundation for Hono integration.
Open guide
ClickHouse Node.js
Node.js-specific ClickHouse integration patterns for non-edge deployments.
Open guide
Next step
Add typed ClickHouse routes to your Hono app
Generate schema bindings with npx @hypequery/cli generate, then call the hypequery query builder inside your Hono route handlers. The response types flow through to the hc() RPC client automatically.