fix(jdbc-v2): preserve DateTime column timezone in getTimestamp

[arimu1]

Summary

Fixes ResultSet.getTimestamp / getObject(..., Timestamp.class) ignoring the column timezone for DateTime / DateTime32 / DateTime64 values (#2787).

BinaryStreamReader already attaches the column (or server/session) timezone when building the internal ZonedDateTime. The JDBC layer was then converting via the caller Calendar / JVM default, re-interpreting wall-clock components and shifting the returned epoch when that timezone differed from the column's (e.g. DateTime64(3, 'UTC') under a non-UTC JVM, or two columns with different declared timezones).

Changes

• ResultSetImpl.getTimestamp: convert using the zone on the ZonedDateTime (column/server zone), not the caller Calendar
• JdbcUtils.convert: preserve absolute instant when converting ZonedDateTime / OffsetDateTime / Instant → Timestamp
• DetachedResultSet.getTimestamp: return the already-materialised absolute Timestamp without re-shifting wall-clock components
• Unit tests for conversion; integration test for multi-timezone column round-trip
• CHANGELOG.md + docs/features.md

Compatibility

• User-visible: getTimestamp for zoned DateTime* columns now returns the correct epoch millis (matching the wire instant). Callers that previously compensated by passing a column-matching Calendar still get the correct value; callers that relied on the incorrect Calendar reinterpretation will see corrected millis.
• JDBC Calendar parameter remains on the API but is not used to re-shift values that already carry timezone information (matches the JDBC javadoc intent for types that store timezone context).

Test plan

• mvn -pl client-v2 test -Dtest=DataTypeUtilsTests (39 tests, unit)
• mvn -pl jdbc-v2 test -Dtest=JdbcUtilsTest (16 tests, unit)
• CI integration: JDBCDateTimeTests.testGetTimestampPreservesInstantAcrossColumnTimezones (requires ClickHouse)

Fixes #2787

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 77ee79b. Configure here.}

[cursor]

getTime disagrees with getTimestamp

Medium Severity

getTimestamp now converts DateTime* values using the column zone so epoch millis match the wire instant, but getTime still takes the column wall-clock LocalDateTime and anchors it with the caller Calendar timezone. On the same row, getTimestamp and getTime can disagree whenever the column timezone and Calendar differ.

Additional Locations (1)

• jdbc-v2/src/main/java/com/clickhouse/jdbc/ResultSetImpl.java#L1122-L1132

 

^{Reviewed by Cursor Bugbot for commit 77ee79b. Configure here.}

[chernser]

@arimu1
This is very correct comment. Calendar used to reinterpret timestamp internal value to make it work according to spec.

[chernser]

@arimu1

Thank you for the contribution!
However fix breaks behavior of the driver - calendar should be used to cast instant to specific timezone.
Most users should migrate to new time framework because it provide more reliable way to work with timestamps.

I'm closing the PR. Please feel free to start discussion in the original issue.

Thanks!