{"id":4476,"library":"clickhouse-pool","title":"ClickHouse Pool","description":"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.","status":"active","version":"0.6.1","language":"python","source_language":"en","source_url":"https://github.com/ericmccarthy7/clickhouse-pool","tags":["database","clickhouse","connection-pool","thread-safe","data-access"],"install":[{"cmd":"pip install clickhouse-pool","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for ClickHouse client connectivity.","package":"clickhouse-driver"},{"reason":"Requires Python 3.9 or higher as of v0.6.0.","package":"python","optional":false}],"imports":[{"symbol":"ChPool","correct":"from clickhouse_pool import ChPool"}],"quickstart":{"code":"import os\nfrom clickhouse_pool import ChPool\n\n# Configure connection details. For production, use environment variables or a config file.\nhost = os.environ.get('CLICKHOUSE_HOST', 'localhost')\nport = int(os.environ.get('CLICKHOUSE_PORT', 9000)) # Native protocol port\nuser = os.environ.get('CLICKHOUSE_USER', 'default')\npassword = os.environ.get('CLICKHOUSE_PASSWORD', '')\ndatabase = os.environ.get('CLICKHOUSE_DB', 'default')\n\n# Initialize the connection pool\n# connections_min and connections_max can be adjusted for your workload\npool = ChPool(\n    host=host, \n    port=port, \n    user=user, \n    password=password, \n    database=database,\n    connections_min=5,\n    connections_max=10\n)\n\ntry:\n    with pool.get_client() as client:\n        # Execute a query\n        result = client.execute(\"SELECT number, 'hello' FROM system.numbers LIMIT 5\")\n        print(\"Query Result:\", result)\n\n        # Example of an insert\n        # client.execute(\"CREATE TABLE IF NOT EXISTS my_table (id UInt64, value String) ENGINE = Memory\")\n        # client.execute(\"INSERT INTO my_table VALUES\", [(1, 'test1'), (2, 'test2')])\n        # print(\"Data inserted.\")\n\n        # result_insert = client.execute(\"SELECT * FROM my_table\")\n        # print(\"Inserted Data:\", result_insert)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Always close all connections in the pool once you're done with it\n    pool.cleanup()\n    print(\"Connection pool cleaned up.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"In 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.","severity":"breaking","affected_versions":"<0.4.0"},{"fix":"Ensure your Python environment is version 3.9 or higher before installing or upgrading to `clickhouse-pool` v0.6.0+.","message":"Version 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.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Upgrade to version 0.5.3 or newer to benefit from the connection pool bug fix.","message":"Previous 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.","severity":"gotcha","affected_versions":"<0.5.3"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Connections 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.6.1':59 'access':80 'activ':52 'aim':28 'bug':65 'built':20 'bump':69 'clickhous':1,4,19,24,37,71 'clickhouse-driv':23 'clickhouse-pool':3 'connect':16,34,45,73 'connection-pool':72 'data':79 'data-access':78 'databas':70 'depend':68 'driver':25 'effici':30 'establish':43 'fix':66 'includ':64 'latest':56 'librari':9,26,50 'maintain':53 'manag':31 'new':44 'overhead':41 'pool':2,5,17,74 'provid':11 'python':8 'queri':48 'receiv':61 'reduc':39 'regular':62 'reus':33 'safe':15,77 'server':38 'thread':14,76 'thread-saf':13,75 'updat':63 'upon':21 'version':57","created_at":"2026-04-12T13:54:17.437239+00:00","updated_at":"2026-04-16T02:33:07.974799+00:00","problems":[{"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:`.","cause":"The application is attempting to acquire more connections from the `ChPool` than its configured `connections_max` limit allows.","error":"clickhouse_pool.pool.TooManyConnections: Too many connections"},{"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.","cause":"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.","error":"DB::Exception: Too many simultaneous queries"},{"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).","cause":"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.","error":"DB::Exception: Connection refused"},{"fix":"Install the library using pip: `pip install clickhouse-pool`.","cause":"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.","error":"ModuleNotFoundError: No module named 'clickhouse_pool'"},{"fix":"Use the `get_client()` method, preferably with a context manager, to acquire a connection: `with pool.get_client() as client: # use client here`.","cause":"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()`.","error":"AttributeError: 'ChPool' object has no attribute 'connect'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://ericmccarthy7.github.io/clickhouse-pool/","github":"https://github.com/ericmccarthy7/clickhouse-pool","docs":null,"changelog":null,"pypi":"https://pypi.org/project/clickhouse-pool/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}