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
py 3.10
✕ build_error
✓ 2.45s
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}")
Errors
Common errors & fixes
ImportError: No module named 'asynch'
The 'asynch' package is not installed in the Python environment.
fixInstall 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.
fixUse 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.
fixEnsure 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.
fixVerify 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.
fixIncrease 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.