aiochclient

What it is and what it does

aiochclient is an async HTTP client for ClickHouse that bridges Python and ClickHouse type systems automatically. It works with either aiohttp or httpx as the underlying HTTP connector and provides methods for executing queries, fetching results all at once, fetching single rows, and streaming results via async iteration. Rows are returned as lightweight objects supporting both index and name-based field access.

The package targets Python 3.10+ and emphasizes performance through optional compiled speedups and Cython compilation. It handles complex ClickHouse types—tuples, arrays, nullable types, decimals, IP addresses, UUIDs, and nested structures—converting them transparently to Python equivalents. The single runtime dependency is sqlparse.

Use it for:

• Fetch large result sets from ClickHouse without loading all rows into memory at once using async iteration.
• Insert bulk data into ClickHouse with automatic type conversion from Python objects.
• Build async applications that query ClickHouse alongside other I/O-bound operations without blocking.
• Work with complex ClickHouse types (tuples, arrays, decimals, UUIDs) and have them automatically converted to Python types.
• Monitor ClickHouse connectivity and health checks in async services using the is_alive() method.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An async HTTP client for ClickHouse that handles type conversion between ClickHouse and Python types, supports streaming and lazy decoding on SELECT queries, and provides a fully typed interface.

Yes, with conditions. Install if you need an async ClickHouse client for Python 3.10+ and are willing to choose and install an HTTP connector. The package is actively maintained, has no known vulnerabilities, and offers good type safety. High install friction and the requirement to select a connector are the main trade-offs; evaluate whether the async model and type conversion features justify the setup overhead for your use case.

Install

aiochclient on PyPI

pip install aiochclient

uv add aiochclient

poetry add aiochclient

Installing aiochclient

Before you install

High install friction: requires Python 3.10+ and a choice of HTTP connector (aiohttp or httpx), with optional compiled speedups and Cython compilation available. Maintenance is active with recent releases and steady repository activity.

License in practice

MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart

pip install aiochclient[aiohttp]

from aiochclient import ChClient

async def main():
    client = ChClient(session)
    await client.execute("CREATE TABLE t (a UInt8) ENGINE = Memory")
    await client.execute("INSERT INTO t VALUES", (1,))
    rows = await client.fetch("SELECT * FROM t")

Requires Python 3.10 or later and either aiohttp or httpx installed as a peer dependency.

Verify before relying

• Whether the stated benchmarks (180k-220k rows/sec SELECT, 50k-80k rows/sec INSERT) remain accurate for current version 2.7.0.
• Whether Cython compilation is automatic or requires manual setup during installation.
• Whether sqlparse is used at runtime or only as a build/test dependency.
• How the optional speedups (cChardet, aiodns, ciso8601) affect installation and performance.

Package facts

Evidence: aiochclient-2.7.0.tar.gz

Keywords: clickhouse, async, python, aiohttp, httpx

Tags

More Front-Ends packages