{"id":1420,"library":"clickhouse-driver","title":"ClickHouse Driver","description":"clickhouse-driver is a Python driver for ClickHouse, implementing the native ClickHouse client-server protocol. It provides a synchronous interface for connecting to and interacting with ClickHouse databases. The current version is 0.2.10, and it generally sees periodic updates with several releases per year addressing bug fixes and Python version compatibility.","status":"active","version":"0.2.10","language":"en","source_language":"en","source_url":"https://github.com/mymarilyn/clickhouse-driver","tags":["database","clickhouse","driver","native-protocol"],"install":[{"cmd":"pip install clickhouse-driver","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for LZ4 compression support with ClickHouse native protocol.","package":"lz4"},{"reason":"Required for timezone handling when working with DateTime and DateTime64 types.","package":"pytz"},{"reason":"Compatibility layer, though less critical for modern Python versions supported.","package":"six"}],"imports":[{"symbol":"Client","correct":"from clickhouse_driver import Client"},{"note":"Exceptions are directly available under `clickhouse_driver.errors`.","wrong":"from clickhouse_driver.exceptions import ...","symbol":"errors","correct":"from clickhouse_driver import errors"}],"quickstart":{"code":"import os\nfrom clickhouse_driver import Client\n\n# Ensure ClickHouse is running, e.g., with Docker:\n# docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 --ulimit nofile=262144:262144 yandex/clickhouse-server\n\nhost = os.environ.get('CLICKHOUSE_HOST', 'localhost')\nport = int(os.environ.get('CLICKHOUSE_PORT', '9000')) # Default native protocol port\nuser = os.environ.get('CLICKHOUSE_USER', 'default')\npassword = os.environ.get('CLICKHOUSE_PASSWORD', '')\n\nclient = Client(host=host, port=port, user=user, password=password)\n\ntry:\n    # Execute a simple query\n    result = client.execute('SELECT 1 + 1 AS two')\n    print(f\"Query result: {result}\")\n\n    # Create a table and insert data\n    client.execute('DROP TABLE IF EXISTS test_data')\n    client.execute('CREATE TABLE test_data (id UInt64, name String) ENGINE = Memory')\n    \n    data_to_insert = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]\n    client.execute('INSERT INTO test_data VALUES', data_to_insert)\n    print(f\"Inserted {len(data_to_insert)} rows.\")\n    \n    # Select data\n    selected_data = client.execute('SELECT id, name FROM test_data ORDER BY id')\n    print(f\"Selected data: {selected_data}\")\n\nfinally:\n    client.disconnect()\n    print(\"Disconnected from ClickHouse.\")","lang":"python","description":"This quickstart demonstrates how to connect to a ClickHouse server using the `Client`, execute simple queries, create a table, insert data using parameterization, and retrieve data. It emphasizes proper connection management and basic CRUD operations. Environment variables are used for connection details for better security and flexibility."},"warnings":[{"fix":"Ensure your Python environment is 3.9 or higher. For older Python versions, use an older `clickhouse-driver` version (e.g., <0.2.9 for Python 3.8).","message":"Python version support has changed significantly. Versions 0.2.0 dropped Python 2 support. Version 0.2.9 dropped support for Python 3.6, 3.7, and 3.8. The current minimum supported Python version is 3.9.","severity":"breaking","affected_versions":">=0.2.0, >=0.2.9"},{"fix":"Explicitly set `secure=True` if you require TLS/SSL. Always specify `port` if you are not using the default native protocol (9000) or HTTP protocol (8123, which is handled by a different client usually).","message":"Default connection parameters for `Client` changed in version 0.2.4. Specifically, `secure` now defaults to `False`, `port` defaults to `9000` (native protocol), and `compression` defaults to `False`. Previously, `secure` might have defaulted to `True` or different port values depending on prior library usage assumptions.","severity":"breaking","affected_versions":">=0.2.4"},{"fix":"Implement a connection pooling mechanism using libraries like `queue` or `DBUtils` in Python, or use an ORM/framework that provides connection pooling capabilities for database drivers.","message":"The `clickhouse-driver` client does not include built-in connection pooling. For applications requiring high concurrency or frequent connections, you will need to implement a connection pool manually or use an external library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass data as a list of tuples to `client.execute()` for `INSERT` statements, e.g., `client.execute('INSERT INTO my_table VALUES', [(1, 'a'), (2, 'b')])`. For `SELECT` or `UPDATE` with parameters, use the `%s` placeholder and pass a tuple/list for the parameters: `client.execute('SELECT * FROM users WHERE id = %s', (user_id,))`.","message":"Always use parameterization for inserting data or executing queries with user-provided values to prevent SQL injection vulnerabilities. Direct string formatting of queries is insecure.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}