clickhouse 0.2.0

A fast, native Dart driver for ClickHouse over the TCP binary protocol — queries, batch inserts, connection pooling, LZ4/LZ4HC/ZSTD compression, and full column-type support.

Changelog

All notable changes to this project are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.2.0

Feature-parity release with the official Go driver on the native transport, validated against ClickHouse 26.6 (plus 24.3 / 25.1). Test coverage 94.7%.

Added

• Native ZSTD compression — a pure-Dart ZSTD codec is now built in for CompressionMethod.zstd in both directions (decodes real libzstd frames, encodes valid frames). A registerCodec(CompressionMethod.zstd, …) still overrides the built-in (e.g. an FFI libzstd).
• Per-query OpenTelemetry span — traceId / spanId / traceState / traceFlags on query() / exec(), overriding the connection-level span.
• Per-query timezone — timezone: on query() / queryRow() / selectAll() decodes DateTime / DateTime64 results in a chosen IANA zone.
• External query cancellation — a cancelTrigger future on query() / exec() aborts an in-flight operation with QueryCancelledException.
• Batch.appendRows(Rows, {flushEvery}) — client-side INSERT … SELECT, piping a query result straight into a batch.
• Custom-type marshaling — ClickHouseValuer (write, unwrapped on append) and ClickHouseScannable + Rows.scanInto / scanIntoByName (read).
• DialContext / dialStrategy — a richer dialer receiving the connection id, resolved address, and options (takes precedence over dial).
• ColumnType.scanType — the Dart Type each column decodes to.
• ErrAcquireConnNoAddress — sentinel thrown when no usable address is configured.
• Language + OS metadata (lv:dart/…, os:…) in the client-info string, so system.query_log records the client runtime.

Changed

• LZ4HC now runs a real high-compression (hash-chain) encoder instead of aliasing plain LZ4; compressLevel scales the search depth.
• maxCompressionBuffer is now honored — a large insert block is split across multiple compressed frames (flushed between chunks) to bound memory.

Fixed

• Timezone-safe DateTime binding — bound DateTime / DateTime64 literals now carry an explicit UTC zone, fixing misreads when the server session timezone is not UTC.
• Multi-row VALUES binding — a List<GroupSet> renders as comma-joined tuples ((…), (…)) instead of an array, for INSERT … VALUES (?,?),(?,?).

0.1.1

Changed

• Enable automated publishing to pub.dev from GitHub Actions trusted publishing.

0.1.0

Initial release. A pure-Dart ClickHouse driver speaking the native TCP binary protocol (port 9000). Validated against ClickHouse 24.3, 25.1, and 26.6.

Connection & pooling

• ClickHouseConnection — TCP dial, handshake, protocol-revision negotiation.
• ClickHousePool — bounded pool with maxOpen/maxIdle, lifetime and idle eviction, wait timeout, health checks, and PoolStats.
• Multiple addresses with ConnOpenStrategy (in-order / round-robin / random).
• TLS (secure, skipVerify, tlsServerName) and a custom dial hook for SSH tunnels, unix sockets, proxies, or instrumentation.
• JWT authentication via a getJwt callback.
• DSN parsing: ClickHouseOptions.fromDsn('clickhouse://user@host:9000/db?...').

Queries & inserts

• query(), exec(), asyncInsert(), and streaming Rows (next, valueAt, valueByName, scan, toMap, scanStruct, columnTypes, totals).
• Batch inserts: prepareBatch() → addRow / appendFromMap / appendStruct / columnar column(i).append*, with send, flush, abort, close.
• Batch pool options: releaseConnection (free the connection until send()) and closeOnFlush.
• Per-query queryId, quotaKey, settings (with ImportantSetting / CustomSetting), server-side {name:Type} parameters, and a full-lifecycle timeout that cancels the query.
• Client-side binding: bind() with positional ?, numeric $N, and named @name placeholders (backtick / comment / string-literal aware).
• External (temporary) tables alongside a query.

Column types

String, FixedString, Int8/16/32/64/128/256, UInt8/16/32/64/128/256, Float32/64, BFloat16, Bool, Date, Date32, DateTime, DateTime64 (timezone-aware, DST-correct via package:timezone), Time, Time64, UUID, Decimal(32/64/128/256), IPv4, IPv6, Enum8/16 (name-mapped), Array, Tuple, Map, Nested, Nullable, LowCardinality, Variant, Dynamic (v1 + v3), JSON (string + object modes), SimpleAggregateFunction, Nothing, all Interval kinds, and the geo types (Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon).

Compression

• LZ4 and LZ4HC with ClickHouse CityHash128 frame checksums.
• Pluggable Codec interface (registerCodec) for ZSTD and others.

Observability

• Callbacks for progress, profile info, profile events, and server logs.
• Structured logger hook and OpenTelemetry trace-context propagation.
• Structured errors: ClickHouseException with ClickHouseErrorCode, plus OpError, ColumnConverterError, BlockError, and Err* sentinels.

Notes

• Native TCP transport only (no HTTP). ZSTD ships as a pluggable codec seam rather than a bundled dependency. Struct mapping uses closures (appendStruct / scanStruct) instead of runtime reflection.