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-poolVerified import paths — ran on the pinned version, not inferred.
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.
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.
Ensure your Python environment is version 3.9 or higher before installing or upgrading to `clickhouse-pool` v0.6.0+.
Upgrade to version 0.5.3 or newer to benefit from the connection pool bug 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.
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.
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:`.
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.
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).
Install the library using pip: `pip install clickhouse-pool`.
Use the `get_client()` method, preferably with a context manager, to acquire a connection: `with pool.get_client() as client: # use client here`.