Registry / database / clickhouse-pool

clickhouse-pool

JSON →
library0.6.1pypypi✓ verified 24d ago

clickhouse-pool is a Python library that provides a thread-safe connection pool for ClickHouse, built upon the `clickhouse-driver` library. It aims to efficiently manage and reuse connections to a ClickHouse server, reducing the overhead of establishing new connections for each query. The library is actively maintained, with its latest version being 0.6.1, and receives regular updates including bug fixes and dependency bumps.

pip install clickhouse-pool
INSTALL
IMPORT
SIG · CLICKHOUSE-POOL
C
clickhouse-pool
databasepythonv0.6.1
Install
2.0s avg
Import
1079ms
Disk
24MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 2s
py 3.11
✓ —
✓ 2s
py 3.12
✓ —
✓ 1.8s
py 3.13
✕ build_error
✕ build_error
py 3.9
✓ —
✓ 2.2s
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ChPool
from clickhouse_pool import ChPool

This quickstart demonstrates how to initialize a `ChPool`, acquire a client using a context manager, execute a simple query, and ensure the pool is cleaned up. Connection parameters can be passed directly or via environment variables.

import os from clickhouse_pool import ChPool # Configure connection details. For production, use environment variables or a config file. host = os.environ.get('CLICKHOUSE_HOST', 'localhost') port = int(os.environ.get('CLICKHOUSE_PORT', 9000)) # Native protocol port user = os.environ.get('CLICKHOUSE_USER', 'default') password = os.environ.get('CLICKHOUSE_PASSWORD', '') database = os.environ.get('CLICKHOUSE_DB', 'default') # Initialize the connection pool # connections_min and connections_max can be adjusted for your workload pool = ChPool( host=host, port=port, user=user, password=password, database=database, connections_min=5, connections_max=10 ) try: with pool.get_client() as client: # Execute a query result = client.execute("SELECT number, 'hello' FROM system.numbers LIMIT 5") print("Query Result:", result) # Example of an insert # client.execute("CREATE TABLE IF NOT EXISTS my_table (id UInt64, value String) ENGINE = Memory") # client.execute("INSERT INTO my_table VALUES", [(1, 'test1'), (2, 'test2')]) # print("Data inserted.") # result_insert = client.execute("SELECT * FROM my_table") # print("Inserted Data:", result_insert) except Exception as e: print(f"An error occurred: {e}") finally: # Always close all connections in the pool once you're done with it pool.cleanup() print("Connection pool cleaned up.")
Debug
Known issues
breakingIn version 0.4.0, the direct methods `get_conn()` and `put_conn()` on the pool were renamed to `pull()` and `push()` respectively. While the recommended approach is now `pool.get_client()` with a context manager, older code directly using these methods will break.
fix
Update direct calls from `pool.get_conn()` to `pool.pull()` and `pool.put_conn()` to `pool.push()`, or ideally, refactor to use the `with pool.get_client() as client:` context manager pattern.
affects: <0.4.0
breakingVersion 0.6.0 introduced a breaking change by updating its Python requirement to Python 3.9 or newer. Installations on older Python versions (e.g., 3.8 or below) will fail or not be able to upgrade.
fix
Ensure your Python environment is version 3.9 or higher before installing or upgrading to `clickhouse-pool` v0.6.0+.
affects: <0.6.0
gotchaPrevious versions (prior to 0.5.3) had a connection pool bug that could lead to improper connection handling. Users on older versions might experience unexpected connection issues.
fix
Upgrade to version 0.5.3 or newer to benefit from the connection pool bug fix.
affects: <0.5.3
gotchaThe `ChPool` is configured with `connections_min` and `connections_max` parameters. If the number of concurrent client requests exceeds `connections_max`, a `ChPoolError.TooManyConnections` exception will be raised. This is intended behavior for a bounded pool but must be handled.
fix
Properly size `connections_max` based on your application's concurrency needs. Implement error handling for `ChPoolError.TooManyConnections` to gracefully manage peak loads or queue requests.
affects: All versions
gotchaConnections acquired from the pool via `get_client()` should ideally be managed within a `with` statement. If manually acquired (e.g., not using a context manager), ensure `pool.cleanup()` is called at the end of your application's lifecycle to properly close all connections and prevent resource leaks.
fix
Always use `with pool.get_client() as client:` for automatic connection management. In scenarios where manual acquisition is necessary, pair every `client = pool.get_client()` with a corresponding `pool.put_client(client)` and ensure `pool.cleanup()` is called when the pool is no longer needed.
affects: All versions
Errors
Common errors & fixes
clickhouse_pool.pool.TooManyConnections: Too many connections
The application is attempting to acquire more connections from the `ChPool` than its configured `connections_max` limit allows.
fix
Increase the `connections_max` parameter during `ChPool` initialization, or ensure connections are properly released back to the pool using `with pool.get_client() as client:`.
DB::Exception: Too many simultaneous queries
The ClickHouse server has reached its configured limit for concurrent queries, often encountered when the application (even one using `clickhouse-pool`) submits too many queries without sufficient server-side capacity.
fix
Optimize ClickHouse queries, increase server-side limits like `max_concurrent_queries` or `distributed_connections_pool_size` in ClickHouse's `config.xml` or `users.xml`. If necessary, reduce the `connections_max` in `clickhouse-pool` to match server capacity.
DB::Exception: Connection refused
The `clickhouse-pool` (via `clickhouse-driver`) failed to establish a connection to the ClickHouse server. This typically indicates the server is not running, incorrect host/port in the connection string, a firewall blocking the connection, or network issues.
fix
Verify the ClickHouse server is running and accessible from the client machine. Check the configured host, port, and credentials. Ensure firewalls (both client and server side) allow traffic on the ClickHouse TCP port (default 9000), and that `listen_host` in ClickHouse's `config.xml` is correctly configured (e.g., `0.0.0.0` for remote access).
ModuleNotFoundError: No module named 'clickhouse_pool'
The `clickhouse-pool` library is not installed in the Python environment, or the environment where the code is being executed does not have access to the installed package.
fix
Install the library using pip: `pip install clickhouse-pool`.
AttributeError: 'ChPool' object has no attribute 'connect'
Users attempting to acquire a connection from the `ChPool` are incorrectly using a `connect()` method, which is not part of the `clickhouse-pool` API. The `ChPool` provides connections through `get_client()`.
fix
Use the `get_client()` method, preferably with a context manager, to acquire a connection: `with pool.get_client() as client: # use client here`.
Upgrade
Version history
0.6.1latest on PyPI · released Aug 19, 2025
Audit
Dependencies
clickhouse-driverrequiredCore dependency for ClickHouse client connectivity.
pythonrequiredRequires Python 3.9 or higher as of v0.6.0.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
clickhouse-pool — pip install clickhouse-pool · libregistry