Prompt
How do I handle time zones correctly in a scheduling app?
Latest observation
Handling time zones correctly in a scheduling app is mostly about one principle:
Store instants in UTC, but preserve the user’s intended local time and time zone for recurring or future events.
Here’s the practical way to do it.
1) Use the right data model
You usually need three pieces of information for an event:
- Start/end instant in UTC
- IANA time zone the user picked, like
America/New_York - Local wall time if the event is meant to occur at a local clock time
Why:
- UTC is great for comparison, sorting, reminders, and actual elapsed time.
- The IANA zone is needed to convert correctly and handle DST.
- Local time matters for events like “every day at 9:00 AM”.
Example
A meeting scheduled for:
2026-03-10 09:00inAmerica/Los_Angeles
Store:
- local datetime:
2026-03-10T09:00:00 - time zone:
America/Los_Angeles - UTC instant:
2026-03-10T16:00:00Z
(depending on DST)
2) Never use fixed offsets alone
Avoid storing only:
UTC-8GMT+2
Offsets change with daylight saving time.
Instead, store IANA zones:
Europe/BerlinAsia/TokyoAmerica/Sao_Paulo
3) Convert at the edges
A good rule:
- Input: convert user local time + zone → UTC for storage
- Display: convert UTC → user’s current/display zone
Keep conversions at the UI/API boundary, not scattered throughout business logic.
4) Be careful with daylight saving time
DST creates two tricky cases:
Nonexistent local times
Example: 2026-03-08 02:30 in some US zones may not exist because clocks jump forward.
You must decide:
- reject it,
- shift it forward,
- or ask the user to choose another time.
Ambiguous local times
Example: 2026-11-01 01:30 may occur twice when clocks fall back.
You need a policy:
- pick the earlier occurrence
- pick the later occurrence
- ask the user to disambiguate
5) For recurring events, store the recurrence in local time
If someone sets:
- “Every Monday at 9:00 AM in New York”
Do not store this as just a UTC timestamp repeated every 7 days.
That will drift when DST changes.
Instead store:
- recurrence rule
- local time
- time zone
Then generate each occurrence in that zone.
6) Distinguish between “absolute” and “wall-clock” events
Absolute event
A webinar starts at a specific moment worldwide.
- Store as UTC instant.
- Display in each viewer’s local zone.
Wall-clock event
A store opens at 8:00 AM local time every day.
- Store as local time + zone.
- Recompute according to local zone rules.
7) Use a solid timezone library
Use your platform’s robust timezone support:
- JavaScript/TypeScript:
Intl.DateTimeFormat,Temporalif available, or libraries likeLuxon - Python:
zoneinfo(preferred),pytzolder - Java/Kotlin:
java.time - Ruby: ActiveSupport with TZInfo
- PostgreSQL:
timestamptzplus explicit zone handling
Avoid hand-rolled timezone math.
8) Pick the correct database type
A common pattern:
timestamp with time zonein Postgres for instants- Separate column for the IANA zone string if needed
Important note:
- In PostgreSQL,
timestamptzstores an instant, not the original zone. - If you need the original zone, save it separately.
9) Make the user’s intended zone explicit
When users create an event, don’t guess too much:
- Let them choose their timezone, or infer it and show it clearly
- Show the zone next to the time
- Make the zone editable
This matters for travelers and remote teams.
10) Test these edge cases
Test:
- DST spring forward
- DST fall back
- events created in one zone and viewed in another
- recurring events across DST boundaries
- users changing timezone after creating events
- all-day events
- midnight boundaries
11) Common mistakes to avoid
- Storing local datetime without zone
- Storing only a UTC offset
- Adding 24 hours for “next day at same local time”
- Using server time zone for user events
- Ignoring DST ambiguity/nonexistence
- Serializing datetimes without timezone info
12) Practical recommendation
A safe default design:
- Single occurrence event:
Store UTC instant + original IANA zone - Recurring event:
Store recurrence rule + local time + IANA zone - Display:
Convert to viewer’s zone as needed
Example flow
User enters:
2026-03-10 09:00- zone:
America/New_York
Your app:
- Validates local time in that zone
- Converts to UTC
- Stores UTC instant and zone
- On display, converts UTC to viewer’s zone
- For recurrence, recomputes each occurrence in
America/New_York
If you want, I can also give you:
- a database schema
- a JavaScript/TypeScript implementation
- or a Python example for handling scheduling correctly.