Registry / database / asynch

asynch

JSON →
library0.4.0pypypi✓ verified 24d ago

asynch is an asynchronous ClickHouse Python driver with native TCP interface support. It reuses many features from `clickhouse-driver` and adheres to PEP249. Currently at version 0.3.1, it undergoes active development with a focus on providing a robust asyncio-compatible interface for ClickHouse interactions.

pip install asynch
INSTALL
IMPORT
SIG · ASYNCH
A
asynch
databasepythonv0.4.0
Install
2.4s avg
Import
285ms
Disk
65MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 2.45s
py 3.11
1/2 runs
✓ 2.4s
py 3.12
1/2 runs
✓ 2.15s
py 3.13
1/2 runs
✓ 2.1s
py 3.9
✕ build_error
✓ 2.9s
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Connection
from asynch import Connection
Pool
from asynch import Pool
Cursor
from asynch.cursors import Cursor
Cursor classes are found in the `asynch.cursors` submodule.
DictCursor
from asynch.cursors import DictCursor
Cursor classes are found in the `asynch.cursors` submodule.
connect
from asynch import Connection # Use Connection class directly
from asynch import connect
The `connect` function was removed in v0.3.0; use `async with Connection(...)` instead.
create_pool
from asynch import Pool # Use Pool class directly
from asynch import create_pool
The `create_pool` function was removed in v0.3.0; use `async with Pool(...)` instead.

This quickstart demonstrates how to establish a connection to a ClickHouse server, create a table, insert data, and fetch results using `asynch`. It showcases the use of `async with` for managing connections and cursors, including `DictCursor` for dictionary-like row access. Environment variables are used for connection details for security.

import asyncio from asynch import Connection from asynch.cursors import DictCursor import os async def main(): # Connect using DSN parameters async with Connection( user=os.environ.get('CH_USER', 'default'), password=os.environ.get('CH_PASSWORD', ''), host=os.environ.get('CH_HOST', '127.0.0.1'), port=int(os.environ.get('CH_PORT', 9000)), database=os.environ.get('CH_DATABASE', 'default'), ) as conn: print(f"Connected to ClickHouse: {conn.opened}") # Create a table async with conn.cursor() as cursor: await cursor.execute( "CREATE TABLE IF NOT EXISTS test_table (id UInt64, value String) ENGINE = MergeTree ORDER BY id" ) print("Table 'test_table' created or already exists.") # Insert data await cursor.execute( "INSERT INTO test_table (id, value) VALUES", [[1, 'hello'], [2, 'world']] ) print("Data inserted.") # Select data using DictCursor async with conn.cursor(cursor=DictCursor) as cursor: await cursor.execute("SELECT id, value FROM test_table ORDER BY id") result = await cursor.fetchall() print(f"Fetched data: {result}") # Clean up (optional) async with conn.cursor() as cursor: await cursor.execute("DROP TABLE IF EXISTS test_table") print("Table 'test_table' dropped.") if __name__ == "__main__": # Example environment variables (replace with your ClickHouse instance details) # os.environ['CH_USER'] = 'my_user' # os.environ['CH_PASSWORD'] = 'my_password' # os.environ['CH_HOST'] = 'localhost' # os.environ['CH_PORT'] = '9000' # os.environ['CH_DATABASE'] = 'my_db' try: asyncio.run(main()) except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe top-level `asynch.connect()` function has been removed. Direct instantiation and usage of `Connection` within an `async with` statement is now required.
fix
Replace `await asynch.connect(...)` with `async with Connection(...) as conn:`.
affects: >=0.3.0
breakingThe `Connection.connected` property, used to check connection status, has been renamed.
fix
Use `Connection.opened` instead of `Connection.connected`.
affects: >=0.3.0
breakingThe `asynch.pool.create_pool()` function has been removed. Connection pooling should now be managed directly using the `Pool` class.
fix
Replace `await create_pool(...)` with `async with Pool(...) as pool:`.
affects: >=0.3.0
gotchaAlways use `async with Connection(...)` and `async with conn.cursor(...)` to ensure connections and cursors are properly managed and closed. Failing to do so can lead to resource leaks and unclosed connections, especially under heavy load.
fix
Wrap `Connection` and cursor operations in `async with` statements to leverage asynchronous context management.
affects: All
gotchaBlocking the asyncio event loop with synchronous I/O or long-running CPU-bound tasks within an async function can severely degrade performance and responsiveness of your application. Ensure all I/O operations are truly asynchronous or offloaded to a thread/process pool.
fix
Identify and refactor blocking calls. Use `await` with async-compatible libraries (like `asynch`) and for CPU-bound tasks, consider `asyncio.to_thread()` or `loop.run_in_executor()`.
affects: All
Errors
Common errors & fixes
ImportError: No module named 'asynch'
The 'asynch' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install asynch'.
AttributeError: module 'asynch' has no attribute 'connect'
The 'connect' function was removed in version 0.3.0; the connection should be established using a Connection instance.
fix
Use a Connection instance with 'async with' syntax: 'async with asynch.Connection(...) as conn:'.
TypeError: 'NoneType' object is not iterable
Attempting to iterate over a result set that is None, possibly due to a failed query execution.
fix
Ensure the query executes successfully and returns a valid result set before iterating.
ValueError: invalid literal for int() with base 10: 'some_string'
Trying to convert a non-numeric string to an integer, often due to incorrect data types in the database.
fix
Verify the data types in the database and ensure that the application handles type conversions appropriately.
asyncio.exceptions.TimeoutError
The operation exceeded the allowed time limit, possibly due to network issues or server unresponsiveness.
fix
Increase the timeout setting or check the network connection and server status.
Upgrade
Version history
0.4.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
clickhouse-cityhashoptionalEnables transport compression.
Agent activity
31 hits · last 30 days
node
26
OpenAI (training)
1
Resources
asynch — pip install asynch · libregistry