Preserve offset timestamps in ClickHouse sink statements
Added explicit UTC conversion for scalar `TIMESTAMP_TZ` values written to existing ClickHouse `DateTime` and `DateTime64` columns, preserving each instant and the destination column's precision.
apache/seatunnel · #12285
Temporal correctness fix
SeaTunnel can now write timezone-aware scalar timestamps to existing ClickHouse DateTime columns without rejecting offsets or collapsing distinct daylight-saving instants.
Problem
The sink passed offset-bearing values through `Timestamp.valueOf`, which rejects ISO-8601 timestamps containing an offset. This prevented writes and could not safely distinguish the two real instants represented by the same local time during a daylight-saving overlap.
Approach
Normalizes each offset timestamp to UTC text and wraps its named SQL parameter with precision-aware `toDateTime` or `toDateTime64` conversion. The same field-aware preparation is applied to inserts, existence checks, updates, and deletes while unrelated field types retain their existing bindings.
Impact and scope
- Enables timezone-aware event data to reach existing ClickHouse temporal columns without losing instant identity.
- Preserves seconds, microseconds, nanoseconds, nullable values, column timezones, and both instants in a daylight-saving overlap.
- Extends the conversion consistently to timezone-aware keys used by upsert, existence-check, update, and delete paths.
Validation
- All 48 connector unit tests and the selected real ClickHouse 23.3.13.6 integration test passed on Java 8 and Java 11, alongside both-module verification and Spotless.
- Server-side epoch assertions covered multiple offsets and column timezones, second through nanosecond precision, nulls, mixed rows, and both daylight-saving overlap instants.
- Two SeaTunnel reviewers approved the fix, and the GitHub-verified merge commit credits Goutam Adwant. `TIMESTAMP_TZ` uses SQL batching rather than the binary insert path, and no throughput equivalence, automatic table creation, nested timestamp support, full engine job, or complete E2E matrix is claimed; GH-9785 remains an open umbrella.