asynch

Major internal refactor: the protocol hot path is now compiled with Cython, modeled on the sister project asyncmy. The public API (Connection, Cursor, DictCursor, Pool, DSNs) is unchanged.

Upgrading: Python 3.11 or newer is required, and asynch now ships platform-specific binary wheels rather than a pure-Python one. Everything else is backwards compatible; pip install -U asynch is enough.

Performance

Measured against clickhouse-driver, the synchronous C-extension driver (500k rows, best of 3; reproduce with make benchmark):

• Exporting 500k rows of a wide events table: 438 ms vs 728 ms (+66%)
• 100 concurrent queries through a pool of 10: 2103 q/s vs 1310 q/s (+61%)
• Per-column decode: DateTime 13.8M vs 2.3M rows/s, String 21.7M vs 15.2M, Decimal +44%, UUID +56%, Array +15%; Int64/Float64 on par
• Small filtered queries, aggregations and batch inserts are server-bound and unchanged - both drivers sit at the wire limit
• New benchmark suite under benchmark/: a realistic wide-table workload, per-column-type micro-benchmarks, concurrency and pool overhead

Packaging & toolchain

• Python 3.11+ required (3.9/3.10 support dropped)
• Wheels are now platform-specific binary wheels built by cibuildwheel (Linux x86_64/arm64, Windows, macOS Intel/ARM); platforms without a wheel compile from sdist and need a C toolchain plus Cython
• Dependency management moved from Poetry to uv (PEP 735 dependency groups); contributors run uv sync --all-groups --all-extras (or make deps)
• Type information ships as generated .pyi stubs validated by stubtest
• CI matrix: Python 3.11–3.14, ClickHouse latest + LTS lines; PyPI publishing via trusted publishing (OIDC)

API

• Support for the modern JSON type (ClickHouse 24.8+). Reading composes a Dynamic/Variant reader per path with the shared-data sub-column and returns nested dicts; writing accepts dicts or JSON text and emits the V2 object framing. Dynamic is readable as a column type in its own right. The pre-24.8 Object('json') spelling keeps its own reader, since modern servers reject the type outright (#142)
• Connection.cancel() / Cursor.cancel() stop a running query from another task. Only the cancel packet is sent - the task awaiting the query owns the read side and drains the stream, so the connection stays usable (#104)
• Connection.last_query exposes the statistics the server reported for the most recent query (elapsed, rows/bytes progress, profile info); previously reachable only as conn._connection.last_query (#85)
• Pool(idle_timeout=...) reaps connections that have been idle for longer than the timeout, down to minsize. Without it the pool grows to its high-water mark and keeps every connection for the process lifetime, which is still the default (#137)
• Pool checkouts cost one liveness ping instead of two: a connection verified on release is not re-pinged when acquired again within liveness_grace seconds (1.0 by default)
• lz4 and zstd moved into the compression extra. They were mandatory even though compression cannot work without the optional clickhouse-cityhash, so every install carried two unusable codec libraries. On Python 3.14+ the stdlib compression.zstd is used and no third-party zstd package is needed at all (#143)
• PEP 249 module surface: apilevel, threadsafety, paramstyle, connect() and the exception hierarchy are now importable from asynch; Cursor.arraysize is a read/write attribute. Additive only - no existing behaviour changes. Based on #159 by @turquoisehealth

Dependencies

• Removed leb128 (hand-rolled unsigned LEB128; also fixes non-canonical varint encodings the signed encoder produced) and pytz (stdlib zoneinfo; tzdata is pulled in on Windows only)

Fixes

• Compressed inserts corrupted the stream and the server dropped the connection: the compressed writer's flush kept its buffer, re-compressing and re-sending every earlier byte. Reported in #149, fix based on #153 by @nils-borrmann-tacto
• A cancelled query left the connection permanently unusable: every later query raised "some records have not been fetched". asyncio.CancelledError is a BaseException, so the teardown branch was skipped and is_query_executing stayed set - which any asyncio.timeout around a query, or a web framework cancelling a request task, would trigger (#93)
• connect_timeout and sync_request_timeout were accepted but never used: a black-holed host hung on the OS connect timeout (taking alt_hosts failover with it), and a ping() against an accepted-but-silent server could stall a pool checkout indefinitely (#114)
• send_receive_timeout is now enforced on socket reads and writes; a server that accepts a connection and then goes silent no longer hangs the client indefinitely (#114)
• A missing codec package reported UnknownCompressionMethod: Unknown compression method: 'lz4', which reads as a typo in a valid method name; it now says to install asynch[compression]
• Streaming forced max_block_size, so a readonly=1 user could not stream at all, and the default buffer of 0 was rejected by the server outright. The setting is only sent when a buffer size was requested (#67)
• A secure connection without an explicit port used 9000 instead of 9440: the port default was applied before the scheme was known, so clickhouses://host/db and Connection(secure=True) both went to the plaintext port. Based on #162 by @stankudrow
• A server-side error (a bad query) disconnected the connection, so every SQL error cost a pooled connection even though the stream is left at a packet boundary and stays usable. Based on #150 by @nils-borrmann-tacto
• Inserting None into a non-Nullable column raised whatever the serializer happened to fail on (TypeError: cannot convert 'NoneType' object to bytes, AttributeError: 'NoneType' object has no attribute 'year'); it now reports the column and expected type. input_format_null_as_default keeps working. Based on #146 by @vizor-games
• alt_hosts never worked as a fallback: the first host's failure aborted the whole connect. Unreachable hosts are now skipped (with the socket torn down between attempts) and NetworkError is raised only if all fail; errors from a server that answers, such as bad credentials, propagate unchanged. Based on #136 by @vlad-zverev
• Pool connections that died while idle were handed back to callers: _refresh "reconnected" them, but connect() returns early on an apparently-open connection, so the reconnect was a no-op. Dead connections are now discarded and replaced. Based on #145 by @nils-borrmann-tacto
• ping() no longer lets OperationalError escape when the peer closes the connection mid-read, which broke transparent pool reconnects. Based on #148 by @nils-borrmann-tacto
• getpass.getuser() raises OSError instead of KeyError since Python 3.13, breaking the handshake where no user name can be determined (e.g. in containers). Based on #156 by @shsailaubay
• DateTime64 was decoded as an unsigned integer: pre-1970 values were silently corrupted on read and failed on write; the wire value is a signed Int64 tick count
• str()/f"{...}" of status/scheme enums returned e.g. ConnectionStatus.opened instead of opened on Python 3.11+
• Cursor.fetchone in streaming mode no longer swallows server errors arriving mid-stream
• The never-implemented use_numpy setting now emits a DeprecationWarning
• Python 2 compat shim (proto/utils/compat.py) removed

0.3