ClickHouse Schema
Generate TypeScript types from your live ClickHouse schema
Hand-written TypeScript interfaces for ClickHouse drift. DateTime is not a Date, UInt64 is not a number, and Nullable columns behave differently to what TypeScript assumes. hypequery introspects your live ClickHouse database and generates correct type mappings for every table and column — automatically.
Command
npx @hypequery/cli generate
Type source
Live ClickHouse database
Update strategy
Re-run after schema changes
ClickHouse types do not map to TypeScript cleanly
DateTime returns as a string formatted as "YYYY-MM-DD HH:MM:SS" — not a JS Date. UInt64 returns as a string to avoid precision loss beyond Number.MAX_SAFE_INTEGER. Nullable(T) returns T | null. If you hand-write interfaces, you are guessing — and TypeScript trusts you.
Hand-written interfaces drift after every schema change
Every ALTER TABLE, every new column, every type change means manually updating TypeScript interfaces. On a team moving fast on ClickHouse, the interfaces are almost always slightly wrong — and the bugs are silent until runtime.
Generic types like any and unknown kill the value of TypeScript
When @clickhouse/client returns any[], teams either cast to interfaces they wrote by hand or give up on types entirely. Both options mean TypeScript is not actually protecting you from the mistakes it exists to catch.
How schema generation works
One command — correct types for every table and column
hypequery connects to your live ClickHouse instance and reads the schema from information_schema. It maps each ClickHouse type to the correct TypeScript type using the same rules the ClickHouse JS client follows at runtime — so the types actually match what comes back.
- 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
Introspect your live ClickHouse schema
Point the CLI at your ClickHouse instance. It reads the schema and outputs a TypeScript interface file. Run it in CI after any schema migration to keep types in sync automatically.
Generated output
Correct ClickHouse-to-TypeScript type mappings
The generated schema file reflects exactly what ClickHouse returns at runtime. No guessing, no hand-writing, no drift. When you add a column or change a type, re-run generate and TypeScript catches every affected query at compile time.
The type mappings are not arbitrary. They follow the same rules as @clickhouse/client — UInt64 comes back as a string because JavaScript cannot represent it precisely as a number. DateTime comes back as a string because ClickHouse uses its own format.
Once the schema is generated, the query builder uses it to provide autocomplete on table names, column names, and return value types across your entire codebase.
Generated schema
TypeScript types reflecting your live ClickHouse database
Every column has the correct TypeScript type — matching what ClickHouse actually returns at runtime. Nullable columns are T | null. UInt64 columns are string. No surprises.
Why teams search for this
Common implementation questions this page should solve
ClickHouse TypeScript type generation
hypequery generate is the only tool that introspects a live ClickHouse schema and outputs correct TypeScript type mappings. It handles the DateTime, UInt64, Nullable, and Decimal cases that hand-written interfaces get wrong.
ClickHouse schema introspection
The generate command reads from information_schema — the same source ClickHouse uses internally. Every table, every column, every type — mapped to TypeScript and written to a file you commit alongside your code.
Keep TypeScript types in sync with ClickHouse schema
The standard workflow is to re-run generate in CI after any schema change. This makes TypeScript the last line of defence against using a column that no longer exists or expecting the wrong type from a changed column.
ClickHouse column type TypeScript mapping
The full type mapping: String→string, UInt8/16/32→number, UInt64→string, Int8/16/32→number, Int64→string, Float32/64→number, Decimal→string, DateTime→string, Date→string, Boolean→boolean, Nullable(T)→T|null, Array(T)→T[].
Further reading
Go deeper with comparison posts and implementation guides
Schemas guide
The full reference for schema generation — options, configuration, and the complete type mapping table.
Open guide
ClickHouse Query Builder
How the generated schema types power the composable query builder.
Open guide
The ClickHouse TypeScript type problem
Why DateTime, UInt64, Nullable, and Decimal return the wrong types and how schema generation fixes it.
Open guide
ClickHouse Migrations
Schema change tooling coming soon — reversible migrations with automatic type regeneration.
Open guide
Next step
Generate TypeScript types from your ClickHouse schema
Run npx @hypequery/cli generate against your ClickHouse instance. You get a typed schema file in seconds — then build typed queries against it.