{"id":20905,"library":"aiochclient","title":"aiochclient","description":"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.","status":"active","version":"2.6.0","language":"python","source_language":"en","source_url":"https://github.com/maximdanilchenko/aiochclient","tags":["clickhouse","async","client","http","database"],"install":[{"cmd":"pip install aiochclient","lang":"bash","label":"Default install"},{"cmd":"pip install aiochclient[aiohttp]","lang":"bash","label":"With aiohttp support"},{"cmd":"pip install aiochclient[httpx]","lang":"bash","label":"With httpx support"}],"dependencies":[{"reason":"Optional HTTP client engine. One of aiohttp or httpx must be installed.","package":"aiohttp","optional":true},{"reason":"Optional HTTP client engine. One of aiohttp or httpx must be installed.","package":"httpx","optional":true}],"imports":[{"note":"Standard import path.","wrong":null,"symbol":"ChClient","correct":"from aiochclient import ChClient"}],"quickstart":{"code":"import asyncio\nfrom aiochclient import ChClient\nfrom aiohttp import ClientSession\n\nasync def main():\n    # No auth is default; for auth use headers or query params (see docs)\n    url = 'http://localhost:8123'\n    async with ClientSession(url, headers={'X-ClickHouse-User': 'default', 'X-ClickHouse-Key': ''}) as session:\n        client = ChClient(session)\n        rows = await client.execute('SELECT version()')\n        for row in rows:\n            print(row)\n\nasyncio.run(main())","lang":"python","description":"Basic usage: create session, execute query, iterate rows."},"warnings":[{"fix":"Install with the desired extra, e.g., pip install aiochclient[aiohttp].","message":"From v2.0.x, aiohttp is no longer a mandatory dependency. You must install either aiochclient[aiohttp] or aiochclient[httpx] explicitly.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove 'user' and 'password' from the URL query; set 'X-ClickHouse-User' and 'X-ClickHouse-Key' headers instead.","message":"In v2.3.0, authentication data is passed via headers instead of query parameters for security reasons. Old code using query params will break.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Use pip install aiochclient[charset_normalizer] if you need charset detection, or remove cchardet from your dependencies.","message":"The cchardet library is abandoned and will cause import errors. aiochclient v2.6.0 fixed this by making cchardet optional.","severity":"deprecated","affected_versions":">=2.6.0"},{"fix":"Use aiohttp client for automatic string decoding, or decode bytes manually.","message":"When using httpx client, responses are read by bytes. If you expect string results, you may need to decode explicitly.","severity":"gotcha","affected_versions":">=2.3.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"pip install aiochclient[aiohttp]","cause":"aiohttp is not installed (aiochclient >=2.0.0 makes HTTP backends optional).","error":"ModuleNotFoundError: No module named 'aiohttp'"},{"fix":"Set 'X-ClickHouse-User' and 'X-ClickHouse-Key' (or 'X-ClickHouse-Password') headers on the ClientSession.","cause":"Authentication is not passed correctly; since v2.3.0 headers are used, not query params.","error":"aiochclient.exceptions.ClickHouseError: Code: 516, e.displayText() = DB::Exception: ... Authentication failed"},{"fix":"from aiochclient import ChClient","cause":"Trying to import from wrong module or outdated install.","error":"AttributeError: module 'aiochclient' has no attribute 'ChClient'"},{"fix":"Use client as a plain object; only query methods like execute() are awaitable.","cause":"Trying to await the client constructor or a non-awaitable method.","error":"TypeError: object ChClient can't be used in 'await' expression"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}