aiochclient

2.6.0 verified Mon Apr 27 auth: no python

Async HTTP ClickHouse client for Python 3.6+. Provides both high-level and low-level interfaces for querying ClickHouse databases over HTTP. Current version 2.6.0, maintained.

pip install aiochclient

Common errors

error ModuleNotFoundError: No module named 'aiohttp' ↓

cause aiohttp is not installed (aiochclient >=2.0.0 makes HTTP backends optional).

fix

pip install aiochclient[aiohttp]

error aiochclient.exceptions.ClickHouseError: Code: 516, e.displayText() = DB::Exception: ... Authentication failed ↓

cause Authentication is not passed correctly; since v2.3.0 headers are used, not query params.

fix

Set 'X-ClickHouse-User' and 'X-ClickHouse-Key' (or 'X-ClickHouse-Password') headers on the ClientSession.

error AttributeError: module 'aiochclient' has no attribute 'ChClient' ↓

cause Trying to import from wrong module or outdated install.

fix

from aiochclient import ChClient

error TypeError: object ChClient can't be used in 'await' expression ↓

cause Trying to await the client constructor or a non-awaitable method.

fix

Use client as a plain object; only query methods like execute() are awaitable.

Warnings

breaking From v2.0.x, aiohttp is no longer a mandatory dependency. You must install either aiochclient[aiohttp] or aiochclient[httpx] explicitly. ↓

fix Install with the desired extra, e.g., pip install aiochclient[aiohttp].

breaking In v2.3.0, authentication data is passed via headers instead of query parameters for security reasons. Old code using query params will break. ↓

fix Remove 'user' and 'password' from the URL query; set 'X-ClickHouse-User' and 'X-ClickHouse-Key' headers instead.

deprecated The cchardet library is abandoned and will cause import errors. aiochclient v2.6.0 fixed this by making cchardet optional. ↓

fix Use pip install aiochclient[charset_normalizer] if you need charset detection, or remove cchardet from your dependencies.

gotcha When using httpx client, responses are read by bytes. If you expect string results, you may need to decode explicitly. ↓

fix Use aiohttp client for automatic string decoding, or decode bytes manually.

Install

pip install aiochclient[aiohttp]

pip install aiochclient[httpx]

Imports

ChClient
```
from aiochclient import ChClient
```
Standard import path.

Quickstart

Basic usage: create session, execute query, iterate rows.

import asyncio
from aiochclient import ChClient
from aiohttp import ClientSession

async def main():
    # No auth is default; for auth use headers or query params (see docs)
    url = 'http://localhost:8123'
    async with ClientSession(url, headers={'X-ClickHouse-User': 'default', 'X-ClickHouse-Key': ''}) as session:
        client = ChClient(session)
        rows = await client.execute('SELECT version()')
        for row in rows:
            print(row)

asyncio.run(main())