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.
Prefer `url`
Use url in new code and CLICKHOUSE_URL in new env files. host is still supported for backward compatibility, but it is deprecated.
Connection Setup
For Node.js environments, hypequery can use the Node.js ClickHouse client automatically:
import { createQueryBuilder } from '@hypequery/clickhouse';
const db = createQueryBuilder({
url: '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({
url: 'https://your-clickhouse-host',
username: 'default',
password: '',
database: 'my_database'
});
const db = createQueryBuilder({
client,
});Connecting an end-user browser directly to ClickHouse is not recommended. Any
credentials shipped to the browser — including values in NEXT_PUBLIC_* or
VITE_* variables — are public, so anyone can run whatever that ClickHouse user
is allowed to. If you do it, restrict the user (read-only, quotas, row
policies); otherwise keep credentials in server-only variables and have browsers
call an authenticated server API such as one built with @hypequery/serve.
Embedded ClickHouse (chDB)
You don't need a ClickHouse server at all: chDB runs the ClickHouse engine inside your Node process, and the chDB team maintains a hypequery adapter (chdb/hypequery). Same builder code, no server — ideal for local development, CI tests, and serverless:
import { createQueryBuilder } from '@hypequery/clickhouse';
import { Session } from 'chdb';
import { chdbAdapter } from 'chdb/hypequery';
const session = new Session('./analytics.chdb'); // or new Session() for in-memory
const db = createQueryBuilder<Schema>({ adapter: chdbAdapter({ session }) });Swap to remote ClickHouse for production by handing createQueryBuilder your connection details instead of the adapter — nothing else changes. See chDB (Embedded ClickHouse) for the full guide.
More generally, createQueryBuilder({ adapter }) accepts any implementation of the DatabaseAdapter contract, so the builder can run against any engine that speaks ClickHouse SQL.
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 |
|---|---|---|---|
url | string | The URL of the ClickHouse server, including protocol and port | Required |
host | string | Deprecated alias for url, still supported for backward compatibility | Optional |
username | string | Username for authentication | 'default' |
password | string | Password for authentication | undefined |
database | string | The database to connect to | 'default' |
For env vars, prefer CLICKHOUSE_URL. Older CLICKHOUSE_HOST setups can continue to work while you migrate.
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: