[czj]

The review of #760 turned up two bugs in the TIMESTAMP_DB_LOCAL branch of PG::BinaryDecoder::Timestamp, both older than any recent change. Neither shows up in CI because every job runs with TZ=UTC.

TimestampLocal subtracted the UTC offset found at the wall clock read as UTC, instead of the one at the real instant, so values near a DST change came back one hour off. With TIMESTAMP_DB_LOCAL alone, the Time was already in UTC mode, its utc_offset was 0, and the wall clock came back labelled UTC (12:00 UTC instead of 10:00 UTC for a Paris summer noon), unlike the text decoder with the same flags.

This version follows PostgreSQL's own rule (DetermineTimeZoneOffset) in C: it reads the offsets one day before and one day after the wall clock with localtime_r, uses that offset when they agree, and otherwise keeps the candidate that maps back to the wall clock, or the later instant when both or neither do (overlaps and gaps). I compared it with wall_clock::timestamp AT TIME ZONE zone for every quarter hour of 1950, 1990, 2011, 2024, 2038, 2040 and 2100 in 10 zones (Paris, London, New York, Santiago, St John's, Cairo, Kathmandu, Sydney, Lord Howe, Apia): 0 mismatches out of 2,454,720 values, for both flag combinations. With 1.7.0, TimestampLocal had 28 (London) to 2,968 (Apia) mismatches, and TIMESTAMP_DB_LOCAL alone was wrong whenever the offset wasn't 0. The new specs hardcode PostgreSQL's answers under TZ=Europe/Paris, including a gap and an overlap in 2024 and both beyond 2038, and fail on master.

An earlier version used Time.local, which I dropped after a review: on macOS, Ruby refuses localtime outside 32-bit time_t, so it was wrong after 2038, and TruffleRuby resolves overlaps differently. tzset() is called per value because glibc's localtime_r doesn't re-read TZ (macOS does). Before 1901-12-14, Ruby on macOS renders local times without the C library's LMT offsets, so those keep master's subtraction, which already round-trips there.

This is a behavior change, so I would rather say it upfront. Anyone who worked around the hour shift or the UTC label will see different values. Speed depends on the platform. These are medians of 7 runs over 10,000 values with Ruby 4.0.9, ranges over 3 alternating rounds in TZ=Europe/Paris and TZ=UTC. TimestampLocal allocates 1 object instead of 2 everywhere. On Linux it gets faster: from 210–320 to 130–160 ns per value on x86_64, and from 370–420 to 245–315 ns on aarch64 (GitHub runners, ubuntu-24.04). On arm64-darwin it gets slower: from ~490 to ~895 ns, because macOS localtime_r is much more expensive than glibc's. TIMESTAMP_DB_LOCAL alone used to skip the work, so it costs more everywhere: from ~110 to ~130–160 ns on x86_64, from ~230 to ~250–320 ns on aarch64, and from ~145 to ~900 ns on macOS. On the same Linux runners, TimestampLocal also matched PostgreSQL for every quarter hour of 1950, 2011, 2024, 2038, 2040 and 2100 in Paris, New York, Sydney, Apia and Lord Howe, against 60 to 430 mismatches for 1.7.0, and the type specs pass under glibc.

The text decoder still differs on overlaps: mktime() picks the DST side on macOS, where PostgreSQL picks standard time. I left it out of this one. Siblings: #759 (the text decoder's timegm(), merged) and #760. The comparison and benchmark scripts are in https://github.com/czj/ruby-pg/tree/bench/binary-local-timestamp if you'd like to rerun them.

Does the per-value tzset() look acceptable to you, or would you rather leave TZ changes at runtime to the caller?

---

🤖 Generated with Claude Code, but prompted, read, and verified by @czj, a caring human :)

[czj]

A deeper review found that relying on Time.local trades the 2024 bugs for new ones: on 64-bit macOS it resolves gaps and overlaps the opposite way to PostgreSQL after 2038, and TruffleRuby picks the summer offset on every overlap, so some values master decoded right come back an hour off. I've moved this back to draft and will rework it with PostgreSQL's own rule (the offsets a day before and after the wall clock, taking the later instant when they differ), with specs pinned to PostgreSQL's answers rather than Time.local's. Sorry for the noise!