{"id":1062,"library":"clickhouse-connect","title":"ClickHouse Connect","description":"ClickHouse Connect is the official Python driver for ClickHouse, providing a high-performance core database interface for Python applications, Pandas DataFrames, NumPy arrays, PyArrow tables, Polars DataFrames, and Apache Superset integration. It leverages the ClickHouse HTTP interface for maximum compatibility and is actively maintained with regular updates.","status":"active","version":"0.15.1","language":"python","source_language":"en","source_url":"https://github.com/ClickHouse/clickhouse-connect","tags":["database","clickhouse","sql","olap","pandas","sqlalchemy","driver"],"install":[{"cmd":"pip install clickhouse-connect","lang":"bash","label":"Install core library"},{"cmd":"pip install \"clickhouse-connect[pandas,numpy,sqlalchemy,polars,arrow,async]\"","lang":"bash","label":"Install with common optional dependencies"}],"dependencies":[{"reason":"Required for secure connections.","package":"certifi","optional":false},{"reason":"HTTP client library (>=1.26).","package":"urllib3","optional":false},{"reason":"Timezone handling.","package":"pytz","optional":false},{"reason":"ZSTD compression support.","package":"zstandard","optional":false},{"reason":"LZ4 compression support.","package":"lz4","optional":false},{"reason":"SQLAlchemy Core dialect and Superset integration.","package":"sqlalchemy","optional":true},{"reason":"Integration with NumPy arrays and Pandas DataFrames.","package":"numpy","optional":true},{"reason":"Integration with Pandas DataFrames.","package":"pandas","optional":true},{"reason":"Integration with Polars DataFrames.","package":"polars","optional":true},{"reason":"Integration with PyArrow tables and Arrow-backed Pandas DataFrames.","package":"pyarrow","optional":true},{"reason":"Required for the native asynchronous client.","package":"aiohttp","optional":true}],"imports":[{"wrong":"import clickhouse_connect","symbol":"get_client","correct":"from clickhouse_connect import get_client"}],"quickstart":{"code":"import clickhouse_connect\nimport os\n\nhost = os.environ.get('CH_HOST', 'localhost')\nport = int(os.environ.get('CH_PORT', 8123)) # Use 8443 for TLS/Cloud\nusername = os.environ.get('CH_USER', 'default')\npassword = os.environ.get('CH_PASSWORD', '')\ndatabase = os.environ.get('CH_DB', 'default')\n\ntry:\n    client = clickhouse_connect.get_client(\n        host=host, \n        port=port,\n        username=username,\n        password=password,\n        database=database,\n        secure= (port == 8443) # Automatically use TLS for 8443\n    )\n    \n    # Test connection\n    client.ping()\n    print(f\"Successfully connected to ClickHouse at {host}:{port}\")\n\n    # Create a table\n    client.command(\n        \"CREATE TABLE IF NOT EXISTS my_test_table (\",\n        \"    id UInt64,\",\n        \"    name String,\",\n        \"    value Float64\",\n        \") ENGINE MergeTree ORDER BY id\"\n    )\n    print(\"Table 'my_test_table' created or already exists.\")\n\n    # Insert data\n    data_to_insert = [\n        [1, 'Alpha', 100.1],\n        [2, 'Beta', 200.2],\n        [3, 'Gamma', 300.3]\n    ]\n    client.insert('my_test_table', data_to_insert, column_names=['id', 'name', 'value'])\n    print(\"Data inserted into 'my_test_table'.\")\n\n    # Query data\n    result = client.query('SELECT * FROM my_test_table ORDER BY id')\n    print(\"Query Results:\")\n    for row in result.result_set:\n        print(row)\n\n    # Example with Pandas (requires 'pandas' extra)\n    try:\n        import pandas as pd\n        df = client.query_df('SELECT * FROM my_test_table')\n        print(\"\\nPandas DataFrame Results:\")\n        print(df)\n    except ImportError:\n        print(\"\\nSkipping Pandas example: 'pandas' not installed. Install with `pip install clickhouse-connect[pandas]`\")\n\nfinally:\n    if 'client' in locals():\n        client.close()\n        print(\"Connection closed.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a ClickHouse server, create a table, insert data, and query it. It includes an example using the `query_df` method for Pandas DataFrames, which requires the `pandas` optional dependency. Credentials are loaded from environment variables for secure usage."},"warnings":[{"fix":"Replace `apply_server_timezone=True` (or similar) with `tz_source='auto'` or other valid options for timezone handling.","message":"The parameter `apply_server_timezone` in client and query methods was renamed to `tz_source` in v0.14.0.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Review insertion logic for `Variant` columns. Ensure that your application expects native type serialization. If using older ClickHouse server versions with `Variant`, compatibility issues may arise.","message":"Version 0.13.0 introduced a native write path for the `Variant` data type. Previously, values were stringified; now they are serialized using their native ClickHouse types client-side, which changes how `Variant` columns store data.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Migrate to `clickhouse_connect.get_async_client()` or `create_async_client()`, which uses `aiohttp`. Ensure `aiohttp` is installed via `pip install clickhouse-connect[async]`.","message":"The legacy executor-based asynchronous client (`AsyncClient(client=...)`) and related parameters (`executor_threads`, `executor`, `pool_mgr`) have been removed. The native aiohttp-based async client is now standard.","severity":"breaking","affected_versions":"future 0.15.x releases (already removed in 0.15.0 changelog, listed as UNRELEASED breaking change prior to 0.15.0)"},{"fix":"Upgrade to Python 3.10 or higher. The library officially tests against Python 3.10 through 3.14.","message":"Python 3.9 support is deprecated and will be removed in version 1.0. Python 3.8 is End-of-Life (EOL) and no longer officially tested or supported; wheels are not built for 3.8 AARCH64 versions.","severity":"deprecated","affected_versions":"Python 3.8 (unsupported), Python 3.9 (deprecated)"},{"fix":"Always install necessary extras for features like Pandas DataFrame integration, even if the base `clickhouse-connect` package is already present.","message":"Optional dependencies (e.g., `numpy`, `pandas`, `pyarrow`, `polars`, `sqlalchemy`) are lazy-loaded. If you intend to use features relying on these, you must install them explicitly using the `[extra]` syntax (e.g., `pip install clickhouse-connect[pandas]`).","severity":"gotcha","affected_versions":">=0.15.0"},{"fix":"For JSON, use separate Python interpreters for different ClickHouse server versions if mixed JSON usage is required. For Pandas, upgrade to Pandas 2.x or later.","message":"For ClickHouse server versions 22.8 and 22.10+, there is an internal serialization format incompatibility for experimental JSON. Using multiple clients with mixed 22.8/22.9 and 22.10+ server versions will break if JSON support is enabled. Pandas 1.x support is also deprecated and will be dropped in 1.0.","severity":"gotcha","affected_versions":"ClickHouse server versions 22.8/22.9 vs 22.10+, clickhouse-connect <1.0 for Pandas 1.x"},{"fix":"Prefix any ClickHouse server-specific settings passed as keyword arguments or query parameters with `ch_` (e.g., `ch_max_rows_to_read=1000`).","message":"When creating a DBAPI Connection or SQLAlchemy DSN, unrecognized keyword arguments or query parameters will now raise an exception instead of being passed as ClickHouse server settings. Server settings should be prefixed with `ch_`.","severity":"gotcha","affected_versions":">=0.9.0"},{"fix":"Ensure that build-essential packages are installed in your environment (e.g., `apk add build-base` for `alpine` Linux) before attempting to install `clickhouse-connect`, or use a Python base image that includes a C compiler.","message":"Installing `clickhouse-connect` in minimal environments (e.g., `alpine` Docker images) may fail if a C compiler is not present. The `lz4` dependency, required by `clickhouse-connect`, often needs to be built from source if a pre-built wheel is unavailable for the specific Python version and architecture, which necessitates a C compiler (like `gcc`).","severity":"breaking","affected_versions":"All versions of `clickhouse-connect` in environments lacking C compilers (e.g., `alpine` Linux), particularly for newer Python versions where `lz4` wheels might be unavailable."}],"env_vars":null,"search_vec":"'activ':46 'apach':32 'applic':22 'array':26 'clickhous':1,3,11,38,52 'compat':43 'connect':2,4 'core':17 'databas':18,51 'datafram':24,30 'driver':9,57 'high':15 'high-perform':14 'http':39 'integr':34 'interfac':19,40 'leverag':36 'maintain':47 'maximum':42 'numpi':25 'offici':7 'olap':54 'panda':23,55 'perform':16 'polar':29 'provid':12 'pyarrow':27 'python':8,21 'regular':49 'sql':53 'sqlalchemi':56 'superset':33 'tabl':28 'updat':50","created_at":"2026-04-01T15:38:08.759707+00:00","updated_at":"2026-04-16T02:31:56.264628+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":50,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://clickhouse.com","github":"https://github.com/ClickHouse/clickhouse-connect","docs":null,"changelog":null,"pypi":"https://pypi.org/project/clickhouse-connect/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"draft"}}