ClickHouse Schema

Generate TypeScript types from your live ClickHouse schema

This is the page for the first problem most TypeScript teams hit on ClickHouse: the database returns one thing, their interfaces claim another, and the compiler happily trusts the wrong version. hypequery fixes that at the schema boundary.

Start with hypequery Read the schemas guide

Command

npx @hypequery/cli generate

Type source

Live ClickHouse database

Update strategy

Re-run after schema changes

ClickHouse runtime types are easy to misread

DateTime is not a JavaScript Date. UInt64 is often not a safe number. Nullable columns change the shape again. If you guess these mappings in an interface, the compiler cannot tell you that the guess is wrong.

Manual interfaces become stale immediately

A renamed column or changed type means updating interfaces by hand, then hoping every cast and helper stayed aligned. That is fragile even on a small team.

Raw clients push the typing problem downstream

If the client gives you `any[]`, somebody still has to decide what the rows look like. That usually ends in a cast, which means the most important boundary in the system is left unchecked.

What generate actually does

Read the live schema and write the TypeScript file you would not maintain by hand

The `generate` command introspects the live ClickHouse schema and writes a database interface you can import everywhere else. The value is not that a file appears. The value is that query code now starts from the same source of truth as the database.

Reads schema from your live ClickHouse information_schema
Correct mappings: DateTime→string, UInt64→string, Nullable(T)→T|null, Decimal→string
Outputs a typed DB interface for every table in the target database
Re-run after any schema change to keep types in sync
Works with ClickHouse Cloud, self-hosted, and local instances

Generate command

Point the CLI at the real database

what-generate-actually-does.ts

This is the only manual step. After that, the generated file becomes the type source for the query builder and the rest of the TypeScript layer.

What you get back

A schema file that reflects runtime reality

The generated output matters because it becomes boring infrastructure: import it once, build queries against it, and let TypeScript flag the places that no longer match after a schema change.

The mappings follow ClickHouse runtime behavior rather than wishful TypeScript shapes. That is why `UInt64` stays a string and why `DateTime` does not become `Date` automatically.

Once this file exists, the rest of the tooling gets simpler: autocomplete is better, casts disappear, and query edits stop feeling like blind string manipulation.

Generated schema

The kind of file you import everywhere else

what-you-get-back.ts

This is the useful artifact: a database-shaped interface that matches what ClickHouse actually returns, not what a relational ORM would prefer it to return.

Where teams usually get stuck

The questions this page should answer

Why this matters more than nicer query syntax

If the schema types are wrong, every nicer abstraction above them is built on sand. Fixing the type source is usually a better first move than introducing more wrappers.

What teams usually automate next

Most teams rerun generation after schema changes or in CI so type drift gets caught before application code is merged.

What this page is not about

This is not a migrations page and it is not an ORM page. It is the narrow piece that keeps runtime ClickHouse shapes and TypeScript expectations aligned.

Where to go after this

Once the schema file exists, the next pages that matter are the query builder and TypeScript workflow pages. That is where the generated types start paying off in everyday code.

Next step

Run generate against a real ClickHouse database

Do it on the schema you already have, then inspect the generated file. You will know quickly whether it removes the casts and wrong assumptions your current code relies on.