Type Generation

Generating TypeScript types from your ClickHouse database is fundamental to building type-safe applications with hypequery. This page explains how to use our CLI tool to generate type definitions from your database schema.

Usage

# Without installing the CLI locally
npx @hypequery/cli generate [options]

# With @hypequery/cli installed in devDependencies
npx hypequery generate [options]

Command Line Options

Environment Variables

The CLI automatically reads connection details from environment variables, so you rarely need to pass credentials as flags:

Legacy aliases such as CLICKHOUSE_URL, CLICKHOUSE_USER, and CLICKHOUSE_PASS are also picked up automatically.

Examples

Basic Usage

# Generate schema with default settings (writes to analytics/schema.ts)
npx hypequery generate

# Specify an output path
npx hypequery generate --output=./src/types/db-schema.ts

# Rerun anytime your ClickHouse schema changes

ClickHouse Cloud or custom hosts

# Inline env vars (or store them in .env)
CLICKHOUSE_HOST=https://your-instance.clickhouse.cloud:8443 \
CLICKHOUSE_DATABASE=default \
CLICKHOUSE_USERNAME=default \
CLICKHOUSE_PASSWORD=your-password \
  npx hypequery generate

Generated Types

The CLI generates two types of TypeScript definitions:

1. Schema Interface: An IntrospectedSchema interface that maps tables and columns to their ClickHouse types, used with the query builder.
2. Record Types: Type-safe interfaces for each table that map columns to their TypeScript equivalents.

Example output:

// Generated by @hypequery/clickhouse
// This file defines TypeScript types based on your ClickHouse database schema

/**
 * Schema interface for use with createQueryBuilder<IntrospectedSchema>()
 * The string literals represent ClickHouse data types for each column
 */
export interface IntrospectedSchema {
  users: {
    id: 'Int32';
    name: 'String';
    email: 'String';
    created_at: 'DateTime';
  };
  // Other tables...
}

// Type-safe record types for each table
export interface UsersRecord {
  id: number;
  name: string;
  email: string;
  created_at: string;
}
// Other record types...

Using Generated Types

Basic Usage

import { createQueryBuilder } from '@hypequery/clickhouse';
import { IntrospectedSchema } from './types/db-schema';

// Create a type-safe query builder
const db = createQueryBuilder<IntrospectedSchema>({
  host: process.env.CLICKHOUSE_HOST,
  username: process.env.CLICKHOUSE_USERNAME,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: process.env.CLICKHOUSE_DATABASE
});

// Now you have full type safety and autocomplete
async function getUsers() {
  return db.table('users')
    .select(['id', 'name', 'email'])
    .where('id', '>', 10)
    .execute();
  // Result type is inferred as { id: number, name: string, email: string }[]
}

Troubleshooting

Common Issues

• Connection Refused: Ensure your ClickHouse server is running and accessible from your current environment.
• Authentication Failed: Check your username and password.
• SSL/Certificate Issues: Ensure your CLICKHOUSE_HOST uses https:// for ClickHouse Cloud and that local certificates are trusted.
• Database Not Found: Verify the database name is correct.

For detailed error messages and troubleshooting, run the CLI with the help flag:

npx hypequery generate --help

Next Steps

Continue: Query Building - Learn the query builder API

Or explore: Filtering - Advanced filtering techniques