{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}