Connecting to ClickHouse
Learn how to connect to ClickHouse databases with hypequery
Connecting to ClickHouse
hypequery provides a type-safe way to connect to ClickHouse from Node.js and browser-capable runtimes.
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 can use the Node.js ClickHouse client automatically:
import { createQueryBuilder } from '@hypequery/clickhouse';
const db = createQueryBuilder({
host: 'http://localhost:8123',
username: 'default',
password: 'password',
database: 'my_database'
});Client Selection:
- In Node.js, hypequery can use
@clickhouse/clientautomatically - In browser or universal setups, pass an explicit
@clickhouse/client-webclient
Requirements:
- Node.js usage requires
@clickhouse/client - Browser or universal usage requires
@clickhouse/client-weband explicit client injection
Browser / universal setup
import { createQueryBuilder } from '@hypequery/clickhouse';
import { createClient } from '@clickhouse/client-web';
const client = createClient({
host: 'https://your-clickhouse-host',
username: 'default',
password: '',
database: 'my_database'
});
const db = createQueryBuilder({
client,
});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.
For additional details on ClickHouse connection options, refer to: