Metadata-Version: 2.4
Name: clickhouse-connect
Version: 1.13.0
Summary: ClickHouse Database Core Driver for Python, Pandas, and Superset
Home-page: https://github.com/ClickHouse/clickhouse-connect
Author: ClickHouse Inc.
Author-email: clients@clickhouse.com
License-Expression: Apache-2.0
Keywords: clickhouse,superset,sqlalchemy,http,driver
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.10,<3.16
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi
Requires-Dist: urllib3>=1.26
Requires-Dist: tzdata; sys_platform == "win32"
Requires-Dist: backports.zstd>=1.3.0; python_version < "3.14"
Requires-Dist: lz4; python_version < "3.14"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy<3.0,>=1.4.40; extra == "sqlalchemy"
Provides-Extra: sqlalchemy-async
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0.44; extra == "sqlalchemy-async"
Requires-Dist: aiohttp>=3.9.0; extra == "sqlalchemy-async"
Provides-Extra: alembic
Requires-Dist: sqlalchemy<3.0,>=1.4.40; extra == "alembic"
Requires-Dist: alembic>=1.18; extra == "alembic"
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Provides-Extra: pandas
Requires-Dist: pandas<4,>=2; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == "polars"
Provides-Extra: arrow
Requires-Dist: pyarrow>=26.0; python_version >= "3.15" and extra == "arrow"
Requires-Dist: pyarrow>=22.0; (python_version >= "3.14" and python_version < "3.15") and extra == "arrow"
Requires-Dist: pyarrow; python_version < "3.14" and extra == "arrow"
Provides-Extra: orjson
Requires-Dist: orjson; extra == "orjson"
Provides-Extra: tzlocal
Requires-Dist: tzlocal>=4.0; extra == "tzlocal"
Provides-Extra: tzdata
Requires-Dist: tzdata; extra == "tzdata"
Provides-Extra: async
Requires-Dist: aiohttp>=3.9.0; extra == "async"
Provides-Extra: lz4
Requires-Dist: lz4>=4.4.5; extra == "lz4"
Provides-Extra: chdb
Requires-Dist: chdb>=4.1.7; extra == "chdb"
Provides-Extra: rust
Requires-Dist: clickhouse-connect-core<0.3,>=0.2.1; extra == "rust"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: license-expression
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

## ClickHouse Connect

[![clickhouse-connect on PyPI](https://img.shields.io/pypi/v/clickhouse-connect?label=clickhouse-connect)](https://pypi.org/project/clickhouse-connect/)
[![clickhouse-connect-core on PyPI](https://img.shields.io/pypi/v/clickhouse-connect-core?label=clickhouse-connect-core)](https://pypi.org/project/clickhouse-connect-core/)

A high performance core database driver for connecting ClickHouse to Python, Pandas, and Superset

* Pandas DataFrames (numpy and arrow-backed). Requires pandas 2.0 or later.
* Numpy Arrays
* PyArrow Tables
* Polars DataFrames
* Superset Connector
* SQLAlchemy Core (select, joins, lightweight deletes; limited feature set)

ClickHouse Connect works with both ClickHouse Cloud and self-hosted ClickHouse. You can [start a free Cloud trial](https://console.clickhouse.cloud/signUp?utm_medium=referral&utm_source=github&utm_campaign=readme&utm_content=clickhouse-connect) or [install ClickHouse](https://clickhouse.com/docs/get-started/setup/install) locally.
For local development, you can also start ClickHouse with the included [Docker Compose configuration](CONTRIBUTING.md#start-clickhouse-in-docker).

ClickHouse Connect uses the ClickHouse HTTP interface for maximum compatibility. An experimental
[chDB](https://clickhouse.com/docs/chdb) backend is also available for running queries against an embedded
in-process engine with `get_client(interface='chdb')`. Install it with `pip install clickhouse-connect[chdb]`.

### Installation

```
pip install clickhouse-connect
```

ClickHouse Connect requires Python 3.10 or higher.

#### Upgrading from 0.x

The 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.

### Releases

`clickhouse-connect` and the optional `clickhouse-connect-core` Rust binding are versioned independently.
The badges above show their latest published PyPI versions.
[GitHub Releases](https://github.com/ClickHouse/clickhouse-connect/releases) track `clickhouse-connect`.
See the [driver changelog](CHANGELOG.md) and the [core binding changelog](rust/ch-core-py/CHANGELOG.md) for release notes.

### Superset Connectivity

ClickHouse Connect is fully integrated with Apache Superset. Previous versions of ClickHouse Connect utilized a
dynamically loaded Superset Engine Spec, but as of Superset v2.1.0 the engine spec was incorporated into the main
Apache Superset project and removed from clickhouse-connect in v0.6.0. If you have issues connecting to earlier
versions of Superset, please use clickhouse-connect v0.5.25.

When creating a Superset Data Source, either use the provided connection dialog, or a SqlAlchemy DSN in the form
`clickhousedb://{username}:{password}@{host}:{port}`.

### SQLAlchemy Implementation

ClickHouse Connect includes a lightweight SQLAlchemy dialect implementation focused on compatibility with **Superset**
and **SQLAlchemy Core**. The synchronous dialect supports SQLAlchemy 1.4 and 2.x. SQLAlchemy 1.4 compatibility is
maintained because Apache Superset currently requires `sqlalchemy>=1.4,<2`.

Use `clickhousedb://` or `clickhousedb+connect://` for synchronous connections. When
`clickhouse-sqlalchemy` is also installed, importing our dialect preserves its
`clickhouse://` registration.
See the [migration guide](clickhouse_connect/cc_sqlalchemy/MIGRATING_FROM_CLICKHOUSE_SQLALCHEMY.md)
for URL and schema-option compatibility.

Async SQLAlchemy usage is available with SQLAlchemy 2.0.44 and later. Install
`clickhouse-connect[sqlalchemy-async]` and use `clickhousedb+async://` with `create_async_engine()`. Results are
buffered. Server-side cursors are not supported. Always await the async engine's `dispose()` method during shutdown
instead of calling `engine.sync_engine.dispose()`.

Supported features include:
- Basic query execution via SQLAlchemy Core
- `SELECT` queries with `JOIN`s (including ClickHouse-specific strictness, `USING`, and `GLOBAL` modifiers),
  `ARRAY JOIN` (single and multi-column), `FINAL`, `SAMPLE`, compound selects, and materialized CTEs
- `VALUES` table function syntax
- Lightweight `DELETE` statements
- Declarative data skipping indexes with `ClickHouseIndex` and explicit inspection with `get_clickhouse_indexes()`
- Declarative SELECT projections with `ClickHouseProjection` and `get_clickhouse_projections()`
- **Alembic** schema migrations (autogenerate, upgrade/downgrade, ClickHouse engine support)

A small number of features require SQLAlchemy 2.x. `Values.cte()` specifically requires SQLAlchemy 2.0.42 or later.
Certain literal-rendering behaviors also require SQLAlchemy 2.x.
All other dialect features, including those used by Superset, work on both 1.4 and 2.x.

Basic ORM usage works for insert-heavy, read-focused workloads: declarative model definitions, `CREATE TABLE`,
`session.add()`, `bulk_save_objects()`, and read queries all function correctly. However, full ORM support is not
provided. UPDATE compilation, foreign key/relationship reflection, autoincrement/RETURNING, and cascade operations
are not implemented. The dialect is best suited for SQLAlchemy Core usage and Superset connectivity.

#### Alembic Migrations

ClickHouse Connect supports [Alembic](https://alembic.sqlalchemy.org/) for schema migrations, including
autogeneration of migration scripts from SQLAlchemy metadata. ClickHouse table engines (`MergeTree`,
`ReplacingMergeTree`, etc.) and dictionaries are preserved through the migration lifecycle.

Supported operations include create/drop table, add/alter/drop/rename column, type and nullability
changes, defaults, comments, and ClickHouse-specific features like `IF EXISTS` guards, column
placement with `AFTER`, and operation-level `clickhouse_settings` on column add/alter/drop.

**Upgrade note:** Alembic compares explicit skip indexes and SELECT projections by default. Objects absent from
managed table metadata generate drops, including objects created only by earlier imperative migrations.
Before upgrading, declare them with `ClickHouseIndex` or `ClickHouseProjection`, exclude unmanaged objects with
Alembic filters, or pass `clickhousedb_compare_indexes=False` or `clickhousedb_compare_projections=False` to
`context.configure()` for the relevant object type. Edits generate separate drop and add operations.
Downgrade restores definitions, but neither direction restores prior materialization. Replacing a projection
discards its existing projection parts. Review the rebuild cost and run `MATERIALIZE PROJECTION` explicitly
when existing parts need the replacement immediately. Index materialization also remains explicit.
Generate index and projection operations with `render_as_batch=False`. Physical batch recreation requires
complete `copy_from` metadata. See the [skip-index documentation](https://clickhouse.com/docs/integrations/language-clients/python/sqlalchemy#sqlalchemy-skip-indexes)
and [projection documentation](https://clickhouse.com/docs/integrations/language-clients/python/sqlalchemy#sqlalchemy-projections)
for declaration, reflection, filtering, and comparison limits.

To get started, install the Alembic extra:

```bash
pip install clickhouse-connect[alembic]
```

For Alembic with the async SQLAlchemy dialect, install `clickhouse-connect[alembic,sqlalchemy-async]`, run
`alembic init -t async alembic`, and replace the generated `alembic/env.py` with the checked-in
[async Alembic environment](examples/alembic_async/env.py). Keep the generated
`script_location = %(here)s/alembic`, or update it if you chose a different migration directory. The example includes
the ClickHouse Alembic hooks and options, runs online migrations through `AsyncConnection.run_sync()`, and compiles
offline migrations without creating an engine.

See the [Alembic worked example](clickhouse_connect/cc_sqlalchemy/alembic/WORKED_EXAMPLE.md) for a
full end-to-end walkthrough covering setup, autogeneration, upgrades, downgrades, and manual
migration operations.

### Asyncio Support

ClickHouse Connect provides native async support using aiohttp. To use the async client,
install the optional async dependency:

```
pip install clickhouse-connect[async]
```

Then create a client with `clickhouse_connect.get_async_client()`. See the
[run_async example](./examples/run_async.py) for more details.

### Complete Documentation

The documentation for ClickHouse Connect has moved to
[ClickHouse Docs](https://clickhouse.com/docs/integrations/python)
