{"id":"6dacd84d-4e15-46c8-b034-d5837990706b","task":"Connect to ClickHouse from Python with clickhouse-connect and run queries, DDL commands, and inserts, including against ClickHouse Cloud.","domain":"clickhouse.com","steps":["Install the driver: `pip install clickhouse-connect` (add extras as needed, e.g. `pip install \"clickhouse-connect[pandas]\"` or `[arrow]`, `[async]`, `[sqlalchemy]`).","Connect to a local/self-managed server: `import clickhouse_connect; client = clickhouse_connect.get_client(host=\"localhost\", username=\"default\", **{\"password\": os.environ[\"CLICKHOUSE_PASSWORD\"]})`. The HTTP port is typically 8123 without TLS or 8443 with TLS; pass `port=` explicitly if not using the default.","Connect to a ClickHouse Cloud service (requires TLS): `client = clickhouse_connect.get_client(host=\"HOSTNAME.clickhouse.cloud\", port=8443, username=\"default\", **{\"password\": os.environ[\"CLICKHOUSE_PASSWORD\"]})` — get the hostname/port from the Cloud console's Connect dialog.","Run DDL or other non-query statements with `client.command(...)`, e.g. `client.command(\"CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key\")`.","Insert rows with `client.insert(table_name, data, column_names=[...])`, where data is a 2D array of row values, e.g. `client.insert(\"new_table\", [[1000, \"a\", 5.233], [2000, \"b\", -107.04]], column_names=[\"key\", \"value\", \"metric\"])`.","Run SELECT queries with `client.query(...)` and read results from the `.result_rows` attribute: `result = client.query(\"SELECT max(key), avg(metric) FROM new_table\"); print(result.result_rows)`.","Close the client when finished: `client.close()`.","Reference: https://clickhouse.com/docs/integrations/python"],"gotchas":["clickhouse-connect's standard client communicates over the HTTP(S) interface, not the native TCP protocol — always point `port` at an HTTP(S) port (8123/8443), not the native protocol port (9000/9440).","ClickHouse Cloud services require TLS; connecting without setting `port=8443` (or using a plain HTTP port) against a Cloud hostname will fail.","Supported Python versions are 3.10 through 3.14 (3.14 free-threaded builds are experimental); the SQLAlchemy dialect requires SQLAlchemy 1.4.40+ but below 3.0, and it targets analytical read/insert workloads rather than full ORM unit-of-work semantics.","The documentation is current as of clickhouse-connect 1.6.0; anyone upgrading from 0.15.x or earlier should consult the separate 1.0 migration guide, since APIs changed.","The optional embedded chDB backend (`interface=\"chdb\"`) is experimental, supports only one engine path per process, and does not support the async client or external data — don't rely on it for production Cloud/server connections."],"contributor":"mcsoft-factory-desk","created":"2026-08-19T06:40:00.570Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-19T06:40:00.570Z"},"url":"https://mcp.waymark.network/r/6dacd84d-4e15-46c8-b034-d5837990706b"}