Octonica.ClickHouseClient 4.1.6

Octonica.ClickHouseClient v4.1.6, 2026-09-16

Backward Incompatible Change

• ExecuteScalar and ExecuteScalarAsync now return null when the result set is empty, matching DbCommand. A SQL NULL is still returned as DBNull.Value. Previously both cases returned DBNull.Value (#94).
• Generic ExecuteScalar<T> and ExecuteScalarAsync<T> throw ClickHouseException with the error code EmptyResult when the result set is empty. Previously this case threw InvalidCastException.

New Feature

• Add property ClickHouseCommand.Settings (ClickHouseQuerySettingCollection) for per-query ClickHouse settings sent in the native protocol. Each ClickHouseQuerySetting keeps the original value, a wire-formatted string, and Important/Custom flags. ClickHouseCommand.Extremes now maps to the extremes setting in that collection.

• Add property ClickHouseCommand.Activity. It allows to pass an OpenTelemetry activity (System.Diagnostics.Activity) with queries executed by the command. The client sends the activity's trace id, span id, W3C trace state and flags in the query so the server can attach the query to the same distributed trace. Overloads of ClickHouseConnection.CreateColumnWriter and CreateColumnWriterAsync accept the same activity for bulk INSERT.

• Add connection setting BusyConnectionMode (ClickHouseBusyConnectionMode, default Wait). With Throw, a command on a connection that already has an active session throws ClickHouseException with the error code OperationInProgress instead of waiting for the session to be released (#59).

Bug Fix

• A second synchronous command on the same thread no longer hangs while a data reader or column writer is open on the connection; it throws ClickHouseException with the error code OperationInProgress (#59).
• ExecuteNonQuery and ExecuteNonQueryAsync no longer break the connection when the server returns an error. The next command on the same connection failed with "The connection is closed."; the connection and its session state are now preserved, matching ExecuteReader and ExecuteScalar (#58).
• Fixed an error when reading the result of a two-level aggregation: "ClickHouseClient received N out-of-order bucket(s) in the server reply." Servers since v25.9 may produce aggregation buckets out of order (#112).
• Fixed an error when reading a column with the Replicated serialization mode whose indexes are serialized as UInt64 values: "Unexpected key (8) size when reading a column with 'replicated' serialization." (#112).