2026-09-08 · 6 min read · Rahul Chitturi
- sql
- timezones
- debugging
A database timestamp can move by hours even when the written date and clock look correct. Column types, SQL literals, session timezone, driver settings, runtime objects, and JSON serialization may each attach or remove timezone meaning.
The same type name does not guarantee identical behavior across database engines, so assumptions imported from another system can create silent shifts.
Name the temporal concept
Decide whether the field stores an instant, a local wall-clock time, or a calendar date. Then document the database type, session zone, parameter type, driver mapping, application representation, and API format.
- Store instants with an unambiguous offset or UTC contract
- Keep local schedules paired with an IANA timezone identifier
- Do not append Z to a value that was never converted to UTC
- Inspect bound parameters instead of only SQL log rendering
Test daylight-saving boundaries
Local times can be skipped or repeated when offset rules change. Define whether nonexistent times fail or move, and which occurrence an ambiguous time selects. Fixed numeric offsets cannot represent future regional rule changes.
Set connection and pool session state explicitly because reused connections may retain a previous tenant or request's timezone. Verify replicas, jobs, migrations, and command-line clients under the same contract.
A Flashman workflow
Use the SQL formatter to inspect queries, timestamp converter for instant and offset checks, JSON formatter for API representations, diff for round trips, and units converter when epoch fields change units.
Test UTC and non-hour offsets, daylight-saving gaps and overlaps, connection reuse, date-only fields, fractional precision, negative epochs if supported, driver upgrades, and database exports.