Connecting to ClickHouse

hypequery provides a robust and type-safe way to connect to ClickHouse databases. The library supports both Node.js and browser environments with intelligent client selection and comprehensive type safety.

Connection Modes

hypequery supports two connection modes, each designed for specific environments:

1. Host-Based Connection (Auto-Detection) - For Node.js Environments

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
Cannot be used in browser environments

2. Manual Client Injection - For Browser Environments

For browser environments, you must explicitly provide a ClickHouse client instance:

import { createClient } from '@clickhouse/client-web';
import { createQueryBuilder } from '@hypequery/clickhouse';

const client = createClient({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password'
});

const db = createQueryBuilder({
  client // Explicitly provide the client
});

Requirements:

Must be running in a browser environment
Requires @clickhouse/client-web to be installed
Client instance must be manually created and injected
Cannot use auto-detection due to browser limitations

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: