ClickHouse.Driver 1.0.0-rc1

• .NETFramework 4.6.2

  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Net.Http (>= 4.3.4)
  • System.Text.Json (>= 10.0.1)

• .NETFramework 4.8

  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Net.Http (>= 4.3.4)
  • System.Text.Json (>= 10.0.1)

• .NETStandard 2.1

  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Text.Json (>= 10.0.1)

• net10.0

  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)

• net6.0

  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Text.Json (>= 10.0.1)

• net8.0

  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Text.Json (>= 10.0.1)

• net9.0

  • Microsoft.Extensions.Http (>= 10.0.1)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
  • Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
  • NodaTime (>= 3.2.3)
  • System.Text.Json (>= 10.0.1)

v?
---

**Breaking Changes:**
* **Removed feature discovery query from `OpenAsync`.** The connection's `OpenAsync()` method no longer executes `SELECT version()` to discover server capabilities. This makes connection opening instantaneous (no network round-trip) but removes the `SupportedFeatures` property from `ClickHouseConnection`. The `ServerVersion` property now throws `InvalidOperationException`.

 **Migration guidance:** If you need to check the server version:
 ```csharp
 using var reader = await connection.ExecuteReaderAsync("SELECT version()");
 reader.Read();
 var version = reader.GetString(0);
 ```

* **DateTime reading behavior changed for columns without explicit timezone.** Previously, `DateTime` columns without a timezone (e.g., `DateTime` vs `DateTime('Europe/Amsterdam')`) would use the server timezone (with `UseServerTimezone=true`) or client timezone to interpret the stored value. Now, these columns return `DateTime` with `Kind=Unspecified`, preserving the wall-clock time exactly as stored without making assumptions about timezone.

 | Column Type | Old Behavior | New Behavior |
 |-------------|--------------|--------------|
 | `DateTime` (no timezone) | Returned with server/client timezone applied | `DateTime` with `Kind=Unspecified` |
 | `DateTime('UTC')` | `DateTime` with `Kind=Utc` | `DateTime` with `Kind=Utc` (unchanged) |
 | `DateTime('Europe/Amsterdam')` | `DateTime` with `Kind=Unspecified` | `DateTime` with `Kind=Unspecified` (unchanged). Reading as DateTimeOffset has correct offset applied. |

 **Migration guidance:** If you need timezone-aware behavior, either:
 1. Use explicit timezones in your column definitions: `DateTime('UTC')` or `DateTime('Europe/Amsterdam')`
 2. Apply the timezone yourself after reading.

* **DateTime writing now respects `DateTime.Kind` property.** Previously, all `DateTime` values were treated as wall-clock time in the target column's timezone regardless of their `Kind` property. The new behavior:

 | DateTime.Kind | Old Behavior | New Behavior |
 |---------------|--------------|--------------|
 | `Utc` | Treated as wall-clock time in column timezone | Preserved as-is (instant is maintained) |
 | `Local` | Treated as wall-clock time in column timezone | Instant is maintained (inserted as UTC timestamp) |
 | `Unspecified` | Treated as wall-clock time in column timezone | Treated as wall-clock time in column timezone (unchanged) |

 Migration guidance: If you were relying on the old behavior where UTC `DateTime` values were reinterpreted in the column timezone, you should change these to `DateTimeKind.Unspecified`:
 ```csharp
 // Old code (worked by accident):
 var utcTime = DateTime.UtcNow;  // Would be reinterpreted in column timezone

 // New code (explicit intent):
 var wallClockTime = DateTime.SpecifyKind(myTime, DateTimeKind.Unspecified);
 ```

   **Important:** When using parameters, you must specify the timezone in the parameter type hint to have string values interpreted in the column timezone:
 ```csharp
 // Correct: timezone in type hint ensures proper interpretation
 command.AddParameter("dt", myDateTime, "DateTime('Europe/Amsterdam')");
 command.CommandText = "INSERT INTO table (dt_column) VALUES ({dt:DateTime('Europe/Amsterdam')})";

 // Gotcha: without timezone hint, UTC is used for interpretation
 command.AddParameter("dt", myDateTime);
 command.CommandText = "INSERT INTO table (dt_column) VALUES ({dt:DateTime})";
 // ^ String value interpreted in UTC, not column timezone!
 ```

 This differs from bulk copy operations where the column timezone is known and used automatically.

* **Removed `UseServerTimezone` setting.** This setting has been removed from the connection string, `ClickHouseClientSettings`, and `ClickHouseConnectionStringBuilder`. It no longer has any effect since columns without timezones now return `Unspecified` DateTime values without any timezone changes applied to what is returned from the server.
* **Moved `ServerTimezone` property from `ClickHouseConnection` to `ClickHouseCommand`.** The server timezone is now available on `ClickHouseCommand.ServerTimezone` after any query execution (the timezone is now extracted from the `X-ClickHouse-Timezone` response header instead of requiring a separate query).
* **Helper and extension methods made internal:** DateTimeConversions, DataReaderExtensions, DictionaryExtensions, EnumerableExtensions, MathUtils, StringExtensions.

**New Features/Improvements:**
* Added support for QBit data type. QBit is a transposed vector column, designed to allow the user to choose a desired quantization level at runtime, speeding up approximate similarity searches. See the GitHub repo for usage examples.
* Added support for setting roles at the connection and command levels.
* Added support for custom headers at the connection level.
* Added support for JWT/Bearer token authentication at both connection and command levels.
* Added `InsertRawStreamAsync` method to `ClickHouseConnection` for inserting raw data streams (CSV, JSON, Parquet, etc.) directly from files or memory. Check out the examples on GitHub for usage examples of all the above.
* When the query id has not been set, it will now be automatically generated by the client.
* Added support for writing `byte[]` values to String type columns via BulkCopy.
* Added `PingAsync` method to `ClickHouseConnection` for checking server availability via the `/ping` endpoint.
* Added support for detecting mid-stream exceptions via the `X-ClickHouse-Exception-Tag` header (ClickHouse 25.11+). When `http_write_exception_in_output_format` is set to 0 on the server, exceptions that occur while streaming results are now properly detected and thrown as `ClickHouseServerException` (which includes the exception message) instead of `EndOfStreamException`.

**Bug Fixes:**
* Fixed a crash when reading a Map with duplicate keys. The current behavior is to return only the last value for a given key.