ClickHouse Toolset

0.37.dev0 verified Mon Apr 27 auth: no python

A collection of tools and utilities for working with ClickHouse databases, including data loading, schema management, and query helpers. Current version 0.37.dev0 (development), with regular releases. Targets Python >=3.8, <3.14.

pip install clickhouse-toolset

Common errors

error ModuleNotFoundError: No module named 'clickhouse_toolset' ↓

cause Package name uses hyphen, but Python import uses underscore. Users often try `import clickhouse-toolset`.

fix

Use pip install clickhouse-toolset and then from clickhouse_toolset import ...

error clickhouse_driver.errors.ServerException: Code: 516. DB::Exception: ... Authentication failed: ... ↓

cause Default password is empty string but sometimes server requires no password, or a different user.

fix

client = ClickHouseClient(host='...', user='default', password='') or password=None if no auth.

error TypeError: Cannot interpret value of type 'NoneType' as a UInt64 ↓

cause Trying to insert a DataFrame cell with None/NaN into a non-nullable column.

fix

Convert None to 0 or use a nullable column type in ClickHouse.

Warnings

gotcha The package is in development (0.37.dev0); APIs may break without notice. Avoid pinning to a dev version in production. ↓

fix Pin to a stable release like 0.36.x when available, or use a fork.

deprecated The `execute` method returns raw tuples by default; future versions may return dicts. Use `as_dict=True` for consistency. ↓

fix client.execute('SELECT 1', as_dict=True)

breaking In version 0.36, the `load_dataframe` function changed its argument order: `table` and `dataframe` swapped positions. ↓

fix For v0.36+: load_dataframe(client, table='my_table', dataframe=df). For older: load_dataframe(df, client, 'my_table').

Imports

ClickHouseClient

wrong

from clickhouse-toolset import ClickHouseClient

correct

from clickhouse_toolset import ClickHouseClient

Hyphen in package name vs underscore in import path

load_dataframe

wrong

from clickhouse_toolset.data import load_dataframe

correct

from clickhouse_toolset import load_dataframe

Function is top-level, not in submodule

Quickstart

Initialize a client and run a simple query.

from clickhouse_toolset import ClickHouseClient

client = ClickHouseClient(host='localhost', port=9000, user='default', password='')
result = client.execute('SELECT version()')
print(result)