ClickHouseConnection

Class: ClickHouseConnection

The main entry point for connecting to a ClickHouse database. Provides static methods to initialize the connection and retrieve the client.

Supports two modes of operation:

  1. Manual injection: Provide a client instance via config.client (required for browser environments)
  2. Auto-detection with fallback: Automatically selects the best client for Node.js environments
    • Tries @clickhouse/client first, falls back to @clickhouse/client-web

Example

// Method 1: Manual injection (required for browser environments)
import { createClient } from '@clickhouse/client-web';
const client = createClient({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password'
});

ClickHouseConnection.initialize({
  host: 'http://localhost:8123',
  database: 'my_database',
  client // Explicitly provide the client
});

// Method 2: Auto-detection (Node.js environments only)
ClickHouseConnection.initialize({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password',
  database: 'my_database'
});

// Get the client to execute queries directly
const client = ClickHouseConnection.getClient();
const result = await client.query({
  query: 'SELECT * FROM my_table',
  format: 'JSONEachRow'
});

Constructors

Constructor

new ClickHouseConnection(): ClickHouseConnection

Returns

ClickHouseConnection

Methods

getClient()

static getClient(): ClickHouseClient

Retrieves the ClickHouse client instance for direct query execution.

Returns

ClickHouseClient

The ClickHouse client instance (union type of Node.js and Web clients)

Throws

Will throw an error if the connection has not been initialized

Example

const client = ClickHouseConnection.getClient();
const result = await client.query({
  query: 'SELECT * FROM my_table',
  format: 'JSONEachRow'
});

getClientInfo()

static getClientInfo(): { type: string; constructorName: string; isNode: boolean }

Gets information about the currently used ClickHouse client.

Returns

{ type: string; constructorName: string; isNode: boolean }

Object containing client type information:

  • type: The client type (‘@clickhouse/client’, ‘@clickhouse/client-web’, or ‘Unknown’)
  • constructorName: The constructor name of the client instance
  • isNode: Whether running in a Node.js environment

Throws

Will throw an error if the connection has not been initialized

Example

const clientInfo = ClickHouseConnection.getClientInfo();
console.log('Client Type:', clientInfo.type);
console.log('Constructor:', clientInfo.constructorName);
console.log('Node.js Environment:', clientInfo.isNode);

getClickHouseSettings()

static getClickHouseSettings(): ClickHouseSettings

Gets the ClickHouseSettings type from the loaded client module. Only available when using auto-detection (not manual injection).

Returns

ClickHouseSettings

The ClickHouseSettings type or an empty object if not available

Example

const settings = ClickHouseConnection.getClickHouseSettings();
console.log('Available settings:', settings);

initialize()

static initialize(config): typeof ClickHouseConnection

Initializes the ClickHouse connection with the provided configuration. This method must be called before any queries can be executed.

Priority order:

  1. If config.client is provided, use it directly (manual injection)
  2. Otherwise, auto-detect the best client for Node.js environments:
    • Tries @clickhouse/client first, falls back to @clickhouse/client-web

Note: Browser environments require manual injection because require() calls don’t work in browsers.

Parameters

config

ClickHouseConfig

The connection configuration options. Can be either:

  • ClickHouseHostConfig: Host-based configuration with connection details
  • ClickHouseClientConfig: Client-based configuration with pre-configured client

Returns

typeof ClickHouseConnection

The ClickHouseConnection class for method chaining

Throws

Will throw an error if no ClickHouse client is available or if configuration is invalid

Example

// Manual injection (required for browser environments)
import { createClient } from '@clickhouse/client-web';
const client = createClient({ host: 'http://localhost:8123' });
ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });

// Auto-detection (Node.js environments only)
ClickHouseConnection.initialize({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password',
  database: 'my_database'
});

Type Guards

isHostConfig()

static isHostConfig(config): config is ClickHouseHostConfig

Type guard to check if a config is a host-based configuration.

Parameters

config

ClickHouseConfig

The configuration to check

Returns

config is ClickHouseHostConfig

True if the config is a host-based configuration

Example

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

const config = {
  host: 'http://localhost:8123',
  username: 'default',
  password: 'password'
};

if (isHostConfig(config)) {
  // TypeScript knows this is a ClickHouseHostConfig
  console.log('Host:', config.host);
}

isClientConfig()

static isClientConfig(config): config is ClickHouseClientConfig

Type guard to check if a config is a client-based configuration.

Parameters

config

ClickHouseConfig

The configuration to check

Returns

config is ClickHouseClientConfig

True if the config is a client-based configuration

Example

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

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

if (isClientConfig(config)) {
  // TypeScript knows this is a ClickHouseClientConfig
  console.log('Using provided client');
}

Configuration Types

ClickHouseHostConfig

Host-based configuration interface:

interface ClickHouseHostConfig extends ClickHouseCommonConfig {
  /** The ClickHouse server host URL. */
  host: string;
}

ClickHouseClientConfig

Client-based configuration interface:

interface ClickHouseClientConfig extends ClickHouseCommonConfig {
  /** Pre-configured ClickHouse client instance. */
  client: ClickHouseClient;
}

ClickHouseCommonConfig

Common configuration options shared by both config types:

interface ClickHouseCommonConfig {
  /** Username for authentication. */
  username?: string;
  /** Password for authentication. */
  password?: string;
  /** The database to connect to. */
  database?: string;
  /** Custom HTTP headers to include with each request. */
  http_headers?: Record<string, string>;
  /** Request timeout in milliseconds. */
  request_timeout?: number;
  /** Compression options for the connection. */
  compression?: {
    response?: boolean;
    request?: boolean;
  };
  /** Application name to identify in ClickHouse server logs. */
  application?: string;
  /** Keep-alive connection settings. */
  keep_alive?: {
    enabled: boolean;
  };
  /** Logger configuration. */
  log?: any;
  /** Additional ClickHouse-specific settings. */
  clickhouse_settings?: ClickHouseSettings;
}

Notes

This library requires one of the following peer dependencies:

  • @clickhouse/client (recommended for Node.js environments)
  • @clickhouse/client-web (for browser/universal environments)

Important: Browser environments require manual injection because require() calls don’t work in browsers.