TCP N9: POCO row insert — InsertRowsAsync<T> over a compiled per-column gather

[alex-clickhouse]

Stacked on #557 (tcp/epic-n5-poco-read) — review that one first; this PR's diff is the write half only.

TCP epic N9: row-oriented insert, both shapes. The read half of Branch 2 landed in #557; this is the mirror, so a POCO now round-trips through the native protocol.

await client.InsertRowsAsync("INSERT INTO t (id, user_name) VALUES", accounts);      // POCO rows
await client.InsertRowsAsync("INSERT INTO t (id, user_name) VALUES", objectRows);    // untyped, positional

What it does

InsertRowsAsync<T>(IReadOnlyList<T>) — one compiled gather per target column, each pulling one property out of every row into the buffer that column is written from. Box-free (except a Variant/Dynamic target, written from object), no per-row delegate hop, and for a fixed-width column the gathered buffer reaches the wire as a single blit. Names match as the read side's do: case-, then underscore-insensitive, with [ClickHouseTcpColumn] / [ClickHouseTcpNotMapped].

InsertRowsAsync(IReadOnlyList<object[]>) — the dynamic tier, positional by the sample block's order. Each column's CLR type comes from the first row that has a value there, so hand-written DateTime values and the raw epoch seconds the untyped read produces are both accepted, and a read-then-reinsert needs no conversion by the caller.

Arrays and List<T> both pass naturally. Arrays are borrowed for the operation; other IReadOnlyList<T> inputs are shallow-copied once into pooled storage so the compiled gathers retain an array fast path. Callers therefore materialize lazy sources before inserting, and must not mutate rows until the operation completes.

No conversion layer of its own. The read side must ask the codec for its conversions, because a column decodes to the raw wire value. Write does not: a codec already accepts DateTime/DateTimeOffset/TimeSpan directly, so the only conversions left are the CLR-level ones a cast would do — nullable lift, enum ordinal, reference upcast. Numeric widening is declined in both directions, which is what keeps "inserts" and "reads back" the same set of shapes.

Decisions worth a look

• Every target column must map to a property, unlike a read, where an unmapped column is skipped: the server expects a value for each column of the statement's list. The remedy the message names is the statement's own column list, which is also how one POCO fills part of a table. A property with no column stays silent.
• A mapping error lands mid-INSERT and must not cost the connection. The target types only arrive in the sample block, so the columns are built there, behind a new internal InsertColumnFactory seam. A factory that throws parks its exception, closes the row stream with no rows, drains, and rethrows once the connection is back to Ready — the course the schema-mismatch path already took. The columns a factory returns are the insert's to dispose; a caller's own columns are untouched, as before.
• "Can this column hold a null" is the codec's question. NullPlaceholder is null is true exactly for Nullable, a nullable LowCardinality, Variant and Dynamic. Asking the CLR instead (default(TWrite) is null) let a null string property into a plain String column through the gather, to fault inside WriteColumn part-way through a block — which terminates the connection. The gather compiles a null test for reference-typed properties too, so it fails before anything is sent, naming the row.
• Nullable's WritableElementTypes was under-reporting. CanWrite has always accepted DateTime? for a Nullable(DateTime) column, but the list reported only the canonical uint? — invisible to a caller who probes with a column, fatal to one that picks a type from the list. Now lifted, along with NullPlaceholderAs.
• Timezone-less calendar writes use the operation's sample context. The columnar, POCO, and untyped planners all resolve target codecs through the sample block's registry and session/server timezone. An Unspecified DateTime now denotes the same session wall clock on write that the read path presents, and the POCO plan cache includes that timezone in its key.
• Rows have a dedicated method name. Keeping row inserts under InsertRowsAsync leaves InsertAsync exclusively columnar, so external concrete IColumn<T>[] implementations and column lists do not collide with a generic row overload.

Known follow-up

LowCardinality(DateTime) reads as DateTime but is written only from uint. It lifts its inner's readable types and not its writable ones, so it is the last codec whose two surfaces disagree. Pre-existing, and the columnar path has always had it, but the POCO layer is what makes it visible. Documented in PocoWriteConversion and left as a follow-up, since closing it means giving the LowCardinality write path a shape per write type as Nullable has.

Testing

2,124 tests pass on net9 against a real server. Overall TCP coverage is 93.94% line / 88.24% branch / 95.52% method; every changed executable line is covered, and the POCO row-buffer path remains at 100% line and branch coverage.

• Per-type coverage rides the corpus: all 203 InsertRoundTripCase cases are inserted as Row<T> and read back. Nested is the one shape rows cannot fill — its writer needs its own column type — so the corpus test asserts the refusal for it rather than skipping.
• POCO→POCO round trip, calendar and enum properties (including the nullable spellings), an insert-only immutable POCO, a narrower column list, a materialized 5,000-row list across several blocks, and the untyped path's positional round trip and read→re-insert.
• Real-server regressions cover timezone-less DateTime and DateTime64(3) with session_timezone = Europe/Amsterdam through columnar, POCO, and untyped row inserts. The columnar case uses an external-style concrete IColumn<T>[], compile-pinning the overload-resolution fix.
• The mid-INSERT refusals all assert the client is still usable afterwards, and the connection-level tests pin that the connection itself stays Ready rather than being redialled, plus the factory's ownership (dispose count) and that the factory's own exception comes back with its identity intact.
• Unit tests cover only what a round trip cannot see: write-type selection, plan-build refusals, cache keys, array borrowing, list copying, null validation, cancellation, and pooled-buffer ownership.

Release builds pass for net8.0, net9.0, and net10.0.

No CHANGELOG/RELEASENOTES entry: no TCP epic PR has one, the assembly being unreleased and [Experimental]. The epic gets a single entry when it ships.

[Copilot]

Pull request overview

Adds the TCP client’s row-oriented insert half, complementing #557’s POCO query support.

Changes:

• Adds POCO and positional object[] insert overloads.
• Compiles cached per-column gather plans with codec-aware null/type handling.
• Preserves connections across mapping failures and adds broad unit/integration coverage.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ClickHouse.Driver.Tcp/Types/Codecs/NullableColumnCodec.cs	Exposes lifted writable types.
ClickHouse.Driver.Tcp/Types/ArrayColumn.cs	Adds pooled-buffer ownership.
ClickHouse.Driver.Tcp/Protocol/ClickHouseTcpConnection.cs	Adds schema-driven column factories.
ClickHouse.Driver.Tcp/Poco/PocoWritePlan.cs	Builds compiled POCO write plans.
ClickHouse.Driver.Tcp/Poco/PocoWriteConversion.cs	Resolves property-to-codec conversions.
ClickHouse.Driver.Tcp/Poco/PocoUntypedColumns.cs	Transposes positional rows.
ClickHouse.Driver.Tcp/Poco/PocoTypeRegistry.cs	Caches write plans.
ClickHouse.Driver.Tcp/Poco/PocoTypeDescriptor.cs	Shares mapped-column descriptions.
ClickHouse.Driver.Tcp/Poco/PocoRowBuffer.cs	Materializes row sources.
ClickHouse.Driver.Tcp/Poco/PocoReadPlan.cs	Uses shared block signatures.
ClickHouse.Driver.Tcp/Poco/PocoColumnBuilder.cs	Compiles per-column gathers.
ClickHouse.Driver.Tcp/Poco/PocoBlockSignature.cs	Centralizes plan cache keys.
ClickHouse.Driver.Tcp/Client/IClickHouseTcpClient.cs	Adds row-insert contracts.
ClickHouse.Driver.Tcp/Client/ClickHouseTcpClient.cs	Implements row inserts.
ClickHouse.Driver.Tcp.Tests/Types/NullableColumnCodecTests.cs	Tests lifted nullable writes.
ClickHouse.Driver.Tcp.Tests/Types/ArrayColumnTests.cs	Tests buffer ownership.
ClickHouse.Driver.Tcp.Tests/Protocol/ClickHouseTcpConnectionInsertTests.cs	Tests factory lifecycle.
ClickHouse.Driver.Tcp.Tests/Poco/PocoWritePlanTests.cs	Tests write-plan behavior.
ClickHouse.Driver.Tcp.Tests/Poco/PocoUntypedColumnsTests.cs	Tests positional transposition.
ClickHouse.Driver.Tcp.Tests/Poco/PocoRowBufferTests.cs	Tests row materialization.
ClickHouse.Driver.Tcp.Tests/Integration/PocoWriteIntegrationTests.cs	Exercises real-server round trips.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

[kavirajk]

LGTM 👍