{"id":20102567,"url":"https://github.com/clickhouse/clickhouse-connect","last_synced_at":"2026-05-27T23:02:53.477Z","repository":{"id":37053435,"uuid":"463288368","full_name":"ClickHouse/clickhouse-connect","owner":"ClickHouse","description":"Python driver/sqlalchemy/superset connectors","archived":false,"fork":false,"pushed_at":"2024-04-11T15:22:57.000Z","size":1558,"stargazers_count":257,"open_issues_count":22,"forks_count":54,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-14T12:28:29.790Z","etag":null,"topics":["clickhouse","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClickHouse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-02-24T20:15:16.000Z","updated_at":"2024-04-17T19:36:41.581Z","dependencies_parsed_at":"2023-10-17T04:57:08.806Z","dependency_job_id":"88a5a03d-1399-42a9-a167-af35435c7f16","html_url":"https://github.com/ClickHouse/clickhouse-connect","commit_stats":null,"previous_names":[],"tags_count":127,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-connect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-connect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-connect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-connect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/clickhouse-connect/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744332,"owners_count":20988783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","python"],"created_at":"2024-11-13T17:31:48.333Z","updated_at":"2026-05-27T23:02:53.469Z","avatar_url":"https://github.com/ClickHouse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## ClickHouse Connect\n\nA high performance core database driver for connecting ClickHouse to Python, Pandas, and Superset\n\n* Pandas DataFrames (numpy and arrow-backed). Requires pandas 2.0 or later.\n* Numpy Arrays\n* PyArrow Tables\n* Polars DataFrames\n* Superset Connector\n* SQLAlchemy Core (select, joins, lightweight deletes; limited feature set)\n\nClickHouse Connect currently uses the ClickHouse HTTP interface for maximum compatibility.\n\n### Installation\n\n```\npip install clickhouse-connect\n```\n\nClickHouse Connect requires Python 3.10 or higher.\n\n#### Upgrading from 0.x\n\nThe 1.0 release includes breaking changes. If you are upgrading from a 0.15.x or earlier release, see [MIGRATION.md](MIGRATION.md) for a guide to the changes and their replacements.\n\n### Superset Connectivity\n\nClickHouse Connect is fully integrated with Apache Superset. Previous versions of ClickHouse Connect utilized a\ndynamically loaded Superset Engine Spec, but as of Superset v2.1.0 the engine spec was incorporated into the main\nApache Superset project and removed from clickhouse-connect in v0.6.0. If you have issues connecting to earlier\nversions of Superset, please use clickhouse-connect v0.5.25.\n\nWhen creating a Superset Data Source, either use the provided connection dialog, or a SqlAlchemy DSN in the form\n`clickhousedb://{username}:{password}@{host}:{port}`.\n\n### SQLAlchemy Implementation\n\nClickHouse Connect includes a lightweight SQLAlchemy dialect implementation focused on compatibility with **Superset**\nand **SQLAlchemy Core**. Both SQLAlchemy 1.4 and 2.x are supported. SQLAlchemy 1.4 compatibility is maintained\nbecause Apache Superset currently requires `sqlalchemy\u003e=1.4,\u003c2`.\n\nSupported features include:\n- Basic query execution via SQLAlchemy Core\n- `SELECT` queries with `JOIN`s (including ClickHouse-specific strictness, `USING`, and `GLOBAL` modifiers),\n  `ARRAY JOIN` (single and multi-column), `FINAL`, and `SAMPLE`\n- `VALUES` table function syntax\n- Lightweight `DELETE` statements\n- **Alembic** schema migrations (autogenerate, upgrade/downgrade, ClickHouse engine support)\n\nA small number of features require SQLAlchemy 2.x: `Values.cte()` and certain literal-rendering behaviors.\nAll other dialect features, including those used by Superset, work on both 1.4 and 2.x.\n\nBasic ORM usage works for insert-heavy, read-focused workloads: declarative model definitions, `CREATE TABLE`,\n`session.add()`, `bulk_save_objects()`, and read queries all function correctly. However, full ORM support is not\nprovided. UPDATE compilation, foreign key/relationship reflection, autoincrement/RETURNING, and cascade operations\nare not implemented. The dialect is best suited for SQLAlchemy Core usage and Superset connectivity.\n\n#### Alembic Migrations\n\nClickHouse Connect supports [Alembic](https://alembic.sqlalchemy.org/) for schema migrations, including\nautogeneration of migration scripts from SQLAlchemy metadata. ClickHouse table engines (`MergeTree`,\n`ReplacingMergeTree`, etc.) and dictionaries are preserved through the migration lifecycle.\n\nSupported operations include create/drop table, add/alter/drop/rename column, type and nullability\nchanges, defaults, comments, and ClickHouse-specific features like `IF EXISTS` guards, column\nplacement with `AFTER`, and operation-level `clickhouse_settings` on column add/alter/drop.\n\nTo get started, install the Alembic extra:\n\n```bash\npip install clickhouse-connect[alembic]\n```\n\nSee the [Alembic worked example](clickhouse_connect/cc_sqlalchemy/alembic/WORKED_EXAMPLE.md) for a\nfull end-to-end walkthrough covering setup, autogeneration, upgrades, downgrades, and manual\nmigration operations.\n\n### Asyncio Support\n\nClickHouse Connect provides native async support using aiohttp. To use the async client,\ninstall the optional async dependency:\n\n```\npip install clickhouse-connect[async]\n```\n\nThen create a client with `clickhouse_connect.get_async_client()`. See the\n[run_async example](./examples/run_async.py) for more details.\n\n### Complete Documentation\n\nThe documentation for ClickHouse Connect has moved to\n[ClickHouse Docs](https://clickhouse.com/docs/integrations/python)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fclickhouse-connect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclickhouse%2Fclickhouse-connect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fclickhouse-connect/lists"}