Add POCO read materialization

[alex-clickhouse]

Summary

Adds a streaming POCO read path for IClickHouseClient and ClickHouseDataReader, backed by a per-client PocoTypeRegistry shared with the existing binary-insert path. Strict v1 type-matching: no implicit conversions, with rich diagnostics on mismatch.

API

• RegisterBinaryInsertType<T>() — existing, unchanged. Insert-only. Kept for backwards compatibility (to be obsoleted in a later release).
• RegisterPocoType<T>() — new. Canonical registration: sets up both insert and read mappings. Both mappings are validated up front; if either validation throws, neither mapping is committed, so the registry is left untouched.
• client.QueryAsync<T>(sql, parameters?, options?, ct?) — IAsyncEnumerable<T>. Streams rows lazily; the underlying reader is disposed on completion, fault, or early break.
• reader.MapTo<T>() — materializes the current row into a fresh T without advancing the reader. Pairs with Read() for ADO.NET-style consumers.

[ClickHouseColumn(Name = ...)] aliases and [ClickHouseNotMapped] exclusion behave the same as on the existing write path.

How it works

1. Registration compiles getters (insert) and setters + a raw-newobj constructor (read) via Expression.Lambda and caches them in a per-client ConcurrentDictionary. The compiled constructor uses raw newobj, so types with required properties are supported.
2. Headers parse when the reader opens. The first MapTo<T> (or first iteration of QueryAsync<T>) builds an ordinal-ordered binding plan from (column ordinal, property index) pairs and fail-fasts on impossible mappings: each column's FrameworkType is checked against the target property type before any rows are materialized. Polymorphic columns (FrameworkType == typeof(object) — Variant/Dynamic/JSON/Object) skip the static check.
3. Per-row, the binding plan drives the loop: null/DBNull is gated by CanAssignNull; otherwise the compiled boxed setter is invoked. An InvalidCastException from the setter (only reachable for polymorphic columns or stale mismatches) is caught and rethrown as InvalidOperationException with column name, ClickHouse type, target property, and returned CLR type.

ClickHouseDataReader.Read() is unchanged. Existing readers keep the buffered CurrentRow available for arbitrary ordinal access alongside MapTo<T>.

Type-matching rules (strict v1)

• Case-sensitive (StringComparer.Ordinal) column-to-property matching.
• Missing columns in the result leave properties at their default value.
• Extra columns in the result are ignored.
• No implicit conversions: no widening (Int8 → Int32), no enum coercion (Enum8 returns string, not your CLR enum), no ClickHouseDecimal ↔ decimal interop. Mismatches throw InvalidOperationException naming the POCO type, property, column, and returned CLR type.
• Static mismatches fail fast at the first MapTo<T> / iteration — before any rows are read.

Limitations

• Read registration requires a public parameterless constructor. Records with primary constructors are rejected on the read side (still fine for RegisterBinaryInsertType, which doesn't construct).
• Init-only, read-only, and non-public-setter properties are silently skipped on the read side and keep their default value even if a matching column is present. The type still registers if at least one property has a public non-init setter.
• required properties are supported (the compiled constructor bypasses required-member enforcement via raw newobj).
• Per-reader bindingPlanCache is a non-concurrent Dictionary — fine because DbDataReader isn't thread-safe by spec; concurrent MapTo<T> calls on a single reader are not supported.
• No conversion hooks in v1. Future opt-in widening / enum / decimal coercions would be additive (a PocoReadOptions flag or [ClickHouseColumn(Convert = true)] attribute), with no public-API break.

Performance

PocoReadBenchmark reads system.numbers projecting (Id, Name, Value) and compares manual GetValue row construction against QueryAsync<T> POCO materialization.

Method	Count	Mean	Ratio	Allocated
ManualGetValue	100k	104.0 ms	1.00	12.73 MB
Poco	100k	115.1 ms	1.14	12.73 MB
ManualGetValue	500k	327.0 ms	1.00	61.55 MB
Poco	500k	341.0 ms	1.05	61.55 MB

Allocations are identical — column values are boxed once during reader buffering and reused. The remaining per-row overhead is the boxed Action<T, object> setter invocation; a future generic-typed-setter pass could close it.

Run on .NET 10 / Linux Ubuntu 22.04 / Intel Core Ultra 7 255U.

Tests

Coverage spans registration edge cases (records, init-only, abstract, write-only, indexers, statics, fields, required, inheritance), the strict-v1 read matrix (alias, missing/extra, case sensitivity, nullable/non-nullable, decimal with and without UseCustomDecimals, type mismatch, unregistered, before-Read, after-end-of-stream, derived, multiple types per reader, parameters, query options), runtime skip of init-only/read-only/private-setter properties, plus review-driven additions:

• atomicity of RegisterPocoType<T> when either side's validation throws,
• QueryAsync<T> cancellation mid-iteration with a successful follow-up query,
• mid-stream server error surfacing as ClickHouseServerException through QueryAsync<T> (gated on ClickHouse 25.11+),
• full nullable-property matrix (Nullable(Int32) null, Nullable(Int32) non-null, plain Int32 → int?).

A new example, examples/Select/Select_005_PocoSelect.cs, demonstrates the calling shapes end-to-end.

---

Note

Medium Risk
New public API on the core client/reader path with strict type rules and shared registry semantics; behavior is well-tested but affects how consumers map query results and register types for insert+read together.

Overview
This PR adds POCO read materialization for query results, mirroring the existing binary-insert POCO story.

Public API: RegisterPocoType<T>() validates and registers both insert and read mappings atomically (either side failing leaves the registry unchanged). RegisterBinaryInsertType<T>() stays insert-only. ClickHouseClient.QueryAsync<T>() streams IAsyncEnumerable<T> and disposes the reader when enumeration ends. ClickHouseDataReader.MapTo<T>() maps the current row without advancing. ClickHouseConnection.RegisterPocoType<T>() forwards to the shared client registry so command readers can use MapTo<T>.

Implementation: The old BinaryInsertTypeRegistry is replaced by a per-client PocoTypeRegistry with separate insert/read mappings, compiled getters/setters/constructors, and readers receive the registry when opened from the client or ADO commands. MapTo<T> builds a per-reader binding plan (case-sensitive column names, static assignability checks, strict v1—no widening/conversions), tracks hasCurrentRow, and clears row state safely on partial read failures.

Docs/tests: v1.4.0 changelog/release notes, a POCO read benchmark, broad unit tests (registration shapes, mapping rules, atomic registration, mid-stream server errors), example Select_006_PocoSelect, and insert tests for ctor-less types vs failed RegisterPocoType.

^{Reviewed by Cursor Bugbot for commit 76505bd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 94.62366% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ckHouse.Driver/ADO/Readers/ClickHouseDataReader.cs	88.13%	4 Missing and 3 partials ⚠️
ClickHouse.Driver/ClickHouseClient.cs	84.61%	0 Missing and 2 partials ⚠️
ClickHouse.Driver/Poco/PocoTypeRegistry.cs	99.10%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR introduces first-class POCO read materialization to the ClickHouse .NET client: a per-client POCO registry is shared between the existing binary insert path and new read APIs, enabling streaming materialization via IAsyncEnumerable<T> and row materialization directly from ClickHouseDataReader.

Changes:

• Added POCO read registration APIs (RegisterPocoReadType<T>(), RegisterPocoType<T>()) and a streaming query API (QueryAsync<T>()) on IClickHouseClient / ClickHouseClient.
• Implemented a unified PocoTypeRegistry that builds insert/read mappings and is threaded through ClickHouseDataReader for GetRecord<T>().
• Added extensive NUnit coverage for registration and read materialization behavior, plus a benchmark, and updated public API + release notes/changelog.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
RELEASENOTES.md	Documents the new POCO read feature set and API surface.
CHANGELOG.md	Adds a v1.4.0 entry describing POCO read support and behavior.
ClickHouse.Driver/PublicAPI/PublicAPI.Unshipped.txt	Declares newly added public APIs for compatibility tracking.
ClickHouse.Driver/IClickHouseClient.cs	Extends the public client interface with POCO read registration and QueryAsync<T>().
ClickHouse.Driver/ClickHouseClient.cs	Implements the new registry-backed registration methods and QueryAsync<T>(); passes registry into readers.
ClickHouse.Driver/ADO/Readers/ClickHouseDataReader.cs	Adds GetRecord<T>() materialization and binding plan caching; stores the per-client registry.
ClickHouse.Driver/ADO/ClickHouseConnection.cs	Exposes POCO read registration passthroughs for ADO.NET users.
ClickHouse.Driver/ADO/ClickHouseCommand.cs	Ensures commands create readers using the client’s shared POCO registry.
ClickHouse.Driver/Copy/PocoTypeRegistry.cs	New unified per-client registry building insert/read mappings and compiled delegates.
ClickHouse.Driver/Copy/PocoMappings.cs	New mapping model types for insert/read paths.
ClickHouse.Driver/Copy/BinaryInsertPropertyInfo.cs	Extends cached property metadata to support both insert and read scenarios.
ClickHouse.Driver/Copy/BinaryInsertTypeRegistry.cs	Removed in favor of PocoTypeRegistry.
ClickHouse.Driver/Copy/BinaryInsertTypeMapping.cs	Removed in favor of split insert/read mapping types.
ClickHouse.Driver.Tests/Copy/PocoRegistrationTests.cs	Adds unit tests for POCO registration validation rules.
ClickHouse.Driver.Tests/Copy/PocoReadTests.cs	Adds end-to-end tests for GetRecord<T>() and QueryAsync<T>().
ClickHouse.Driver.Tests/Copy/PocoEdgeCaseTests.cs	Adds extensive edge-case coverage for supported/unsupported POCO shapes.
ClickHouse.Driver.Benchmark/PocoReadBenchmark.cs	Adds a benchmark comparing POCO materialization vs manual GetValue.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

[DanielBunting]

Small thing - since this adds members to IClickHouseClient, downstream implementors will need to add the new members on upgrade, which is source-breaking for them (eg. custom wrappers for logging/retry/routing).

Could you potentially add something along the lines of:

void RegisterPocoType<T>() where T : class =>
    throw new NotSupportedException(
        $"{GetType().Name} does not implement RegisterPocoType<T>. " +
        "Added in v1.4.0 — update your implementation or use ClickHouseClient.");

Existing implementations keep compiling and wrappers get a clear runtime error until they upgrade.

[DanielBunting]

Worth considering whether this should be opt-in rather than the default. The 'silent skip' failure mode is hard to diagnose; registration succeeds, queries run, and every property comes back at its CLR default with no exception, no log, nothing to help diagnose.

Could RegisterPocoType fail registration if the POCO has read-unmappable properties (init-only, read-only, non-public-setter) by default, with a PocoReadOptions type with a bool opt-out for users who genuinely want the current skip behaviour?

[github-actions]

Triage

Category: feature • Risk: high

Summary
This PR adds a full POCO read materialization path that mirrors the existing binary-insert story. It introduces RegisterPocoType<T>() (atomically registers insert + read, validating both up front) on IClickHouseClient and ClickHouseConnection; ClickHouseClient.QueryAsync<T>() returning a lazily-streaming IAsyncEnumerable<T> with reader disposal on completion/fault/break; and ClickHouseDataReader.MapTo<T>() for ADO.NET-style per-row materialization. Internally, the old Copy/BinaryInsertTypeRegistry (plus BinaryInsertTypeMapping.cs and BinaryInsertPropertyInfo.cs) is deleted and replaced by a new Poco/PocoTypeRegistry that owns both insert and read mappings. The registry is threaded through ClickHouseCommand.ExecuteDbDataReaderAsync so command readers can also call MapTo<T>. ClickHouseDataReader.Read() is modified to track hasCurrentRow state. The PR includes a benchmark, broad unit tests, CHANGELOG/RELEASENOTES entries, and a new example.

What this impacts

• IClickHouseClient / ClickHouseClient (Utility/) — new public API: RegisterPocoType<T>, QueryAsync<T>
• ADO/ClickHouseDataReader — new public API: MapTo<T>; hot-path state change in Read(); non-concurrent bindingPlanCache per reader
• ADO/ClickHouseCommand, ADO/ClickHouseConnection — registry wired in; new public RegisterPocoType<T> on connection
• Copy/ subsystem replaced by Poco/ — internal refactor affecting the binary-insert path via renamed types (PocoInsertMapping, PocoPropertyInfo)
• PublicAPI/PublicAPI.Unshipped.txt — 4 new entries; both ClickHouseClient and ClickHouseConnection users, plus any ADO.NET consumer using ClickHouseDataReader directly

Concerns

• Risk: high — cross-module refactor: ADO/ (ClickHouseDataReader, ClickHouseCommand, ClickHouseConnection), Utility/ (ClickHouseClient), Copy/ (three files deleted), new Poco/ directory — four of the named high-risk modules move together.
• Risk: high — public API surface: Four new entries on consumer-facing types (IClickHouseClient, ClickHouseConnection, ClickHouseDataReader) added to PublicAPI.Unshipped.txt; correctly tracked, but warrants human sign-off on the shape.
• Risk: high — hot-path state change in Read(): hasCurrentRow is cleared before the per-column deserialization loop and set true only on success. Any mid-row EndOfStreamException (or future exception) now leaves hasCurrentRow = false. This is intentionally defensive but changes observable state on exception paths that existing consumers might currently catch-and-continue.

Required reviewer action

• High: PR body must include an architectural description before review.