TCP T3: usage examples for the native client

[alex-clickhouse]

Epic T3. Adds 30 runnable examples for the native (TCP) client and reorganises examples/ so the two
transports live side by side.

Stacked on #594 (tcp/epic-u1-block-projection), which acts on section B of the follow-up list these examples produced. Below that, #592 froze the surface they use.

Replaces #593, closed so the stack reads in number order.

What is here

30 native examples in seven directories, numbered from 001 within each one, as the HTTP examples are:

Directory	Examples	Subject
Tcp/Core	001-004	first query, connection string and options, DI, migrating from the HTTP client
Tcp/Read	001-004	the three read tiers, blocks and columns, parameters, POCOs
Tcp/Write	001-002	columnar insert, composite write shapes
Tcp/Types	001-005	scalars, date and time, composites, Variant/Dynamic/JSON, QBit
Tcp/Connection	001-004	sessions, pool tuning, TLS, timeouts
Tcp/Advanced	001-006	settings and query id, callbacks, cancellation, errors and retries, compression, server info
Tcp/Observability	001-005	logging, OpenTelemetry, metadata blocks, health checks, Testcontainers

Each is a public static class with a public static Task Run(), registered in Program.cs and listed in
the README, and each prints what it did and what came back rather than asserting.

The 54 HTTP examples move to examples/Http/ (pure renames) and now take their server from one place.

Reorganisation

• examples/ExampleConfig.cs is the single source of the endpoint. CLICKHOUSE_HOST,
  CLICKHOUSE_HTTP_PORT, CLICKHOUSE_TCP_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
  CLICKHOUSE_DATABASE, or CLICKHOUSE_{HTTP,TCP}_CONNECTION_STRING to replace a whole string. Four
  examples are exempt and say so: two teach configuration, two start their own server.
• examples/ExamplePreflight.cs reaches the endpoints the selected examples need before any of them
  runs, and prints what to fix. It exits non-zero rather than skipping, because CI runs the suite unfiltered
  and a skip would leave the run green with nothing exercised.
• dotnet run -- --tcp and --http run one transport; --list takes them too.
• examples/AGENTS.md (plus a CLAUDE.md pointing at it) writes down the five steps for adding an
  example — the registration in Program.cs is the one that gets forgotten — the naming rule that keeps the
  two transports' class names apart, and the table-naming and endpoint rules.
• examples/Tcp/README.md covers the port, the CHTCP0001 opt-in, what the native client cannot do
  (no format other than Native, no ADO.NET and so no ORM, no JWT, no custom headers, no per-query role or
  database) and what only it does (blocks, real sessions, live progress, block compression, QBit planes,
  W3C trace context).

.github/workflows/examples.yml publishes 9000 and watches ClickHouse.Driver.Tcp/**.

Review

The branch was reviewed per directory. Everything the review raised about examples/ is fixed in
3f88b6e, the last commit — four P1s in the runner (a whole-string override that did not reach the
builders; --http running the three examples that need a cluster, Cloud or a token; a transport flag
ignored alongside --filter; preflight holding up the two self-contained examples), version gates for
QBit and Geometry, which fail outright on 25.8, and nine prose claims that were wrong.

Two behaviours worth calling out, because they are the kind of thing an example teaches by accident:

• 42 stream loops ended in break after their first block. Stopping a StreamAsync enumeration early makes
  the client cancel the query and discard the connection, so every one of those loops was demonstrating the
  abandon path. All 42 read a single-block result, so they now drain.
• Every fixed-name table is dropped before it is created as well as after. A run interrupted before its
  finally used to break the next run at CREATE TABLE, and the runner pauses between examples when
  interactive, so that is a common way to leave one behind.

What the review found about the driver rather than the examples is recorded as follow-ups, not fixed here:
TimeoutException cannot be attributed to the pool, the dial or the read, so a health check cannot honestly
separate "busy" from "down"; and GetServerInfoAsync describes the connection it borrowed, which a version
gate can outlive.

The surface #594 adds

Five examples use it, so the block tier is taught with the projection and composition it has:

• Types/Tcp_001_ScalarTypes writes an Enum from a label and a String from raw bytes, then reads both
  back through IEnumColumn, IStringColumn, and Block.ReadAs. Its earlier advice was to change the
  schema to FixedString(N) for bytes.
• Types/Tcp_002_DateTimeAndTimezones reads a whole DateTime column as DateTimeOffset.
• Types/Tcp_003_CompositeRead walks every column through the non-generic composite views, naming the trap
  that a wrong type argument on a typed view compiles and never matches.
• Types/Tcp_004_VariantDynamicJson names each row's alternative from IVariantColumn.TypeNames rather than
  printing bare discriminators.
• Write/Tcp_002_CompositeWrites builds the flat array shape with ClickHouseTcpColumn.CreateArray, and asks
  ClickHouseTcpTypes.CanWrite which CLR types a target column accepts instead of listing them by hand.

Verification

Ran against a live 26.6.1.1193:

• dotnet run -- --tcp, 30/30, exit 0, re-run after the TCP U1: projection and composition on the block tier #594 surface went in.
• dotnet run, 79 examples across both transports, exit 0. Every exception in the logs is one an example
  raises on purpose.
• CLICKHOUSE_TCP_PORT=1 dotnet run -- --filter tcptestcontainers starts its container and handshakes,
  confirming the self-contained examples no longer depend on the configured endpoint.

No changelog fragment: this is an epic branch in the tcp/** stack.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!