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:
- Manual injection: Provide a client instance via
config.client
(required for browser environments) - 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 instanceisNode
: 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:
- If
config.client
is provided, use it directly (manual injection) - 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 detailsClickHouseClientConfig
: 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.