Map DateTimeOffset to DateTime64 and fix composite component reads (#53)

[alex-clickhouse]

Fixes #53.

Problem

The provider had no mapping for DateTimeOffset. EF Core therefore fell back to
DateTimeOffsetToStringConverter through the value-converter selector, and made a String column
without a warning. Two failures came from this:

• A query against a real DateTime64 column failed with TYPE_MISMATCH, because the provider
  declared the parameter as String.
• SaveChanges could not write the value at all.

Solution

A DateTimeOffset property now maps to DateTime64(7, 'UTC') through the new
ClickHouseDateTimeOffsetTypeMapping. No value converter is used, so the driver receives the
DateTimeOffset directly on the query parameter path and on the bulk insert path.

Three design decisions are important:

The store type pins the timezone to 'UTC'. For a timezone-less parameter type such as
DateTime64(7), the driver sends a UTC wall clock, and the server then reads it in
session_timezone. The instant moves when that setting is not UTC. A UTC-pinned store type removes
this dependency on server configuration.

Precision 7 is one .NET tick (100 ns). The round trip is therefore exact, and no value comes
back truncated. Precision 7 also covers the full DateTimeOffset range, so MinValue and MaxValue
work as open-ended range limits.

The offset is not kept. ClickHouse has no type that stores a UTC offset. DateTime64 holds an
instant, and a declared timezone only decides how that instant is rendered. The instant is preserved
and the offset is not, so a value read back carries the offset of the column's declared timezone.
The README records this, together with the alternative for a caller who must keep the offset.

Also in this PR: three composite-mapping defects

Work on #53 exposed these. They are in the same PR because DateTimeOffset inside a composite type
does not work without them, and because they touch the same resolution path in
ClickHouseTypeMappingSource.

1. Composite columns did not convert their components on read. Array(T), Map(K, V) and
   Tuple(...) read the whole column through GetValue, so a component mapping's own read pipeline
   never ran. Any component whose CLR type differs from the driver's type threw
   InvalidCastException. This was not new with DateTimeOffset — DateOnly[],
   Dictionary<string, DateOnly> and Tuple<DateOnly, …> were already affected, because DateOnly
   also arrives from the driver as a DateTime.

   The new ClickHouseComponentConversion helper rebuilds the composite component by component. It
   applies the same two steps EF Core applies to a scalar column: the mapping's data-reader
   conversion, then its ValueConverter. A component that needs no conversion keeps the direct
   cast, and a runtime fast path returns the driver's array untouched when it is already the target
   type.

2. Array(Nullable(T)) DDL was double-wrapped for a value-type element, which gave
   Array(Nullable(Nullable(T))). ClickHouse rejects this with Nested type Nullable(T) cannot be inside Nullable type, so EnsureCreated and migrations both failed.

3. A component mapping ignored the CLR component type. One store type can serve more than one
   CLR type: DateTime64 serves DateTime and DateTimeOffset, and Date32 serves DateTime and
   DateOnly. Resolving a component from an explicit store type always picked the default CLR type,
   which gave the composite the wrong element type and broke change tracking.

Tests

DateTimeOffsetMappingTests (680 lines) and CompositeElementConversionTests (484 lines), 59 tests
in total. All run against a real ClickHouse server through Testcontainers, as the guidance in
AGENTS.md prefers.

They cover the round trip at each precision, a non-UTC column timezone, the ambiguous
daylight-saving hour, ordering and comparison, MinValue/MaxValue, SQL literal generation,
HasPrecision, the bulk insert path, and DateTimeOffset and DateOnly inside Array, Map,
Tuple and nested composites.

Known limits

• Writing a component that needs a ValueConverter still does not work, because the bulk insert
  path passes model values to the driver without applying converters (SaveChanges fails for value-converted properties: bulk insert path does not apply the converter #54). An enum inside a
  composite is written as its raw ordinal. Reading such a column works.
• DateTimeOffset members such as .Year do not translate to SQL yet (No LINQ translation for DateTime members and methods #55).
• In a column timezone with daylight saving, the repeated hour when clocks go back is ambiguous,
  because the driver gives a wall clock and drops the offset. The provider recovers the instant
  where the zone's standard offset is zero, such as Europe/London. Where both candidate offsets
  are non-zero, such as Europe/Paris, the value can read back one hour early. The default 'UTC'
  store type is not affected.

Behaviour change

A DateTimeOffset property that relied on the old String column now resolves to
DateTime64(7, 'UTC'). Add HasConversion<string>() to keep the previous shape. Note that
HasColumnType("String") on its own is not enough, because it adds no converter.

Note for the reviewer

ClickHouseEngineBuilder.cs has two XML doc comments only, which explain the relationship between
WithOrderBy and WithPrimaryKey. This is unrelated to #53. Say the word and I will take it out.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 27 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...age/Internal/Mapping/ClickHouseTupleTypeMapping.cs	76.08%	8 Missing and 3 partials ⚠️
.../Internal/Mapping/ClickHouseComponentConversion.cs	82.05%	7 Missing ⚠️
...se/Storage/Internal/ClickHouseTypeMappingSource.cs	93.18%	0 Missing and 3 partials ⚠️
...ternal/Mapping/ClickHouseNullableElementMapping.cs	57.14%	1 Missing and 2 partials ⚠️
...orage/Internal/Mapping/ClickHouseMapTypeMapping.cs	89.47%	0 Missing and 2 partials ⚠️
...age/Internal/Mapping/ClickHouseArrayTypeMapping.cs	94.44%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds native DateTimeOffset support and repairs composite component materialization.

Changes:

• Maps DateTimeOffset to UTC-pinned DateTime64(7).
• Converts Array, Map, and Tuple components during reads.
• Adds integration coverage and user documentation.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
ClickHouseDateTimeOffsetTypeMapping.cs	Implements mapping, literals, and timezone-aware reads.
ClickHouseComponentConversion.cs	Centralizes component conversion.
ClickHouseArrayTypeMapping.cs	Rebuilds arrays requiring conversion.
ClickHouseMapTypeMapping.cs	Rebuilds converted map entries.
ClickHouseTupleTypeMapping.cs	Converts tuple components.
ClickHouseNullableElementMapping.cs	Handles nullable component reads and DDL.
ClickHouseTypeMappingSource.cs	Registers and resolves new mappings.
ClickHouseEngineBuilder.cs	Documents sorting and primary keys.
DateTimeOffsetMappingTests.cs	Tests mapping and round trips.
CompositeElementConversionTests.cs	Tests composite materialization.
README.md	Documents DateTimeOffset behavior.
CHANGELOG.md	Records feature and fixes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[alex-clickhouse]

Let's make sure we have tests with Fixed/UTC±HH:MM:SS timezone (which clickhouse supports and .NET doesn't natively...there is support for them in the client lib).