Connecting to ClickHouse

hypequery provides a robust and type-safe way to connect to ClickHouse databases from Node.js runtimes, with intelligent client selection and comprehensive type safety.

Tip: skip manual setup

Run npx hypequery init to scaffold your ClickHouse connection, env variables, and schema generation so you can skip the manual setup steps below.

Connection Setup

For Node.js environments, hypequery automatically uses the Node.js ClickHouse client:

import { createQueryBuilder } from '@hypequery/clickhouse';

const db = createQueryBuilder({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password',
  database: 'my_database'
});

Client Selection:

Automatically uses @clickhouse/client (Node.js client)

Requirements:

Must be running in a Node.js environment
Requires @clickhouse/client to be installed

Connection Options

hypequery supports all connection options provided by the official ClickHouse JavaScript client with full type safety:

Core Connection Options

Option	Type	Description	Default
`host`	`string`	The URL of the ClickHouse server, including protocol and port	Required
`username`	`string`	Username for authentication	’default’
`password`	`string`	Password for authentication	undefined
`database`	`string`	The database to connect to	’default’

Advanced Options

Option	Type	Description
`http_headers`	`Record<string, string>`	Custom HTTP headers to include with each request
`request_timeout`	`number`	Request timeout in milliseconds
`compression`	`{ response?: boolean; request?: boolean }`	Enable compression for requests and/or responses
`application`	`string`	Application name to identify in ClickHouse server logs
`keep_alive`	`{ enabled: boolean }`	Keep-alive connection settings
`log`	`any`	Logger configuration
`clickhouse_settings`	`ClickHouseSettings`	Additional ClickHouse-specific settings

References and Resources

hypequery’s connection options are fully compatible with the official ClickHouse JavaScript client. Our connection implementation provides enhanced type safety and intelligent client selection while maintaining full compatibility.