Name the kind of time first#
Most timezone comments argue about two kinds of value:
- An instant is a point on the timeline, the same everywhere, such as a log timestamp or a token expiry. Python calls a
datetimewith an offset "aware" (aware and naive objects), PostgreSQL stores instants intimestamptz, and BigQuery inTIMESTAMP. - A wall-clock time has no zone of its own, such as a store's opening hour or a daily 01:00 backup. It is a naive
datetime, a PostgreSQLtimestampwithout time zone (date/time types) or a BigQueryDATETIME(data types).
A naive value can also stand for an instant by convention, usually "naive means UTC". That convention is correct as long as every reader and writer follows it, and the bug appears where one of them uses the machine's local zone instead.
So the first question about a comment such as "this datetime is naive" or "this ignores the time zone" is which kind the value is supposed to be. The second is where it crosses into code that assumes the other kind.
A Calendar argument the driver now ignores#
In October 2026, a pull request to Google's BigQuery JDBC driver changed the Calendar overloads of setTimestamp and getTimestamp. The author explained the bug: the old code "extracted the JVM-local wall-clock fields (ts.toLocalDateTime()) and re-anchored them in cal.getTimeZone()," "shifting the epoch instant whenever the Calendar timezone differed from the JVM default timezone." The fix ignores the Calendar, because "A java.sql.Timestamp already represents an absolute UTC epoch instant (milliseconds + nanos)," "and BigQuery's TIMESTAMP type is a timezone-aware absolute instant." (pull request)
gemini-code-assist's review summary objected that "ignoring the Calendar parameter entirely may cause issues with timezone-naive DATETIME values, which should be interpreted using the provided Calendar's timezone." (review) The inline threads are resolved and hidden. The author pushed a commit titled "address pr feedback", and the pull request merged on 13 October 2026 with the Calendar still ignored:
public void setTimestamp(int parameterIndex, Timestamp value, Calendar calendar)
throws SQLException {
checkClosed();
- setTimestamp(
- parameterIndex, BigQueryTemporalUtility.convertTimestampWithCalendar(value, calendar));
+ setTimestamp(parameterIndex, value);
}
Both sides have a point, and the code decides between them. JDBC says a driver "uses the Calendar object to construct an SQL TIMESTAMP value" (PreparedStatement.setTimestamp), which matters for databases that store wall-clock time. For this driver, the question is which BigQuery type a Timestamp parameter becomes. In BigQueryTypeRegistry.java at the merge commit, both the TIMESTAMP and the DATETIME descriptors accept java.sql.Timestamp, but registration uses putIfAbsent and the TIMESTAMP descriptor registers first. A bound Timestamp is therefore sent as TIMESTAMP, an instant, and the author's reasoning holds for the setters.
The tests back that up. The changed tests run the Calendar overloads with America/New_York and Asia/Tokyo, with a fixed instant, new Timestamp(1700000000000L), and assert that the same instant comes back. What we did not check is the read path: whether getTimestamp with a Calendar can return a DATETIME value, which is the case the bot named. That needs its own test with a DATETIME column.
A naive datetime that is the convention#
The opposite comment, "replace this naive datetime with an aware one", can be wrong for the same reason. A google-cloud-python pull request merged on 13 November 2026 replaced the deprecated datetime.utcnow() in the ndb library. Its description warns that DateTimeProperty._validate() "rejects offset-aware values unless the property is configured with tzinfo", so "A plain substitution would therefore make auto_now raise BadValueError for every property without tzinfo." The helper it added strips the offset "to keep returning the naive-UTC value ndb has always stored and compared." (pull request) Here naive means UTC by contract, and an aware value is the bug.
Test in zones that are not UTC#
CI usually runs in UTC, where a naive local time and a naive UTC time are the same value. A test of the overdue-job check in vllm-project/aibrix passed in CI and failed on a developer machine in Asia/Kolkata, because it built a naive local time that the code read as UTC (pull request). Run timezone tests with at least two non-UTC zones on opposite sides of UTC, as the JDBC tests do, and include a daylight saving change. In Python with zoneinfo:
ny = ZoneInfo("America/New_York")
datetime(2026, 11, 1, 1, 30, tzinfo=ny).utcoffset() # -4 hours
datetime(2026, 11, 1, 1, 30, fold=1, tzinfo=ny).utcoffset() # -5 hours
The same wall time occurs twice on that date. Adding timedelta(days=1) to midnight on 1 November gives midnight on 2 November, 25 hours later. Comparing a naive and an aware datetime raises TypeError: can't compare offset-naive and offset-aware datetimes.
Decide from the kind of value#
| What you find | Answer |
|---|---|
| A conversion reads wall-clock fields from an instant, or the reverse | Change the code, and test with two non-UTC zones |
| The value is naive, and the code documents and enforces "naive means UTC" | Dismiss, citing the convention, as ndb's validation does |
| The value is naive, and some reader or writer uses local time | Change it to an aware value or a fixed convention at that boundary |
| The value is a wall-clock time, such as a schedule, and the comment asks to store UTC | Dismiss, and keep the zone name beside the value |
| The code adds days or hours across a daylight saving change | Test the change date explicitly |
If a date already shows one day off in the browser, the guide to finding where the date shifted traces the conversion from the API response to the screen.