Time zones and AT TIME ZONE in PostgreSQL - Deep Dive

Overview - Time zones and AT TIME ZONE

What is it?

Time zones in databases help store and convert times correctly across different regions of the world. PostgreSQL provides the AT TIME ZONE clause to convert timestamps between time zones easily. This lets you work with dates and times in a way that respects local time differences. It is essential for applications that serve users in multiple time zones.

Why it matters

Without proper time zone handling, times can be confusing or wrong, causing missed meetings, incorrect logs, or wrong data analysis. Imagine scheduling a call with someone in another country without knowing their local time — it would be chaotic. AT TIME ZONE solves this by letting databases convert and display times correctly, avoiding costly mistakes.

Where it fits

Before learning this, you should understand basic date and time types in PostgreSQL. After mastering time zones and AT TIME ZONE, you can explore advanced scheduling, internationalization, and timestamp indexing for performance.

Mental Model

Core Idea

AT TIME ZONE converts a timestamp from one time zone to another by shifting the time value accordingly.

Think of it like...

It's like changing the clock on your wall when you travel to a new country so that the time matches the local time there.

Timestamp with time zone (timestamptz)
       │
       ▼
  ┌───────────────┐
  │ Original time  │
  │ in one zone    │
  └───────────────┘
       │ AT TIME ZONE 'zone'
       ▼
  ┌───────────────┐
  │ Converted time │
  │ in new zone    │
  └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding PostgreSQL Timestamp Types

Concept: Learn the difference between timestamp without time zone and timestamp with time zone.

PostgreSQL has two main timestamp types: 'timestamp without time zone' stores a date and time without any time zone info. 'timestamp with time zone' (timestamptz) stores the time in UTC internally and converts it to your session's time zone when displayed.

Result

You know that timestamptz always represents an absolute point in time, while timestamp without time zone is just a date and time without context.

Understanding these types is key because AT TIME ZONE behaves differently depending on which type you use.

2

Foundation

What Is a Time Zone in PostgreSQL?

Concept: Time zones are named regions with specific offsets from UTC, including daylight saving rules.

PostgreSQL knows many time zones like 'UTC', 'America/New_York', or 'Europe/London'. Each has rules for offset from UTC that can change with daylight saving time. You can see the current time zone with SHOW TIMEZONE; and set it with SET TIMEZONE TO 'zone';

Result

You can identify and use named time zones to convert times correctly.

Knowing time zones lets you understand how PostgreSQL shifts times when converting between zones.

3

Intermediate

Using AT TIME ZONE with timestamp without time zone

🤔Before reading on: do you think AT TIME ZONE adds or removes time zone info when used on timestamp without time zone? Commit to your answer.

Concept: When used on timestamp without time zone, AT TIME ZONE treats the timestamp as if it is in the given zone and converts it to timestamptz (UTC).

Example: SELECT '2024-06-01 12:00:00'::timestamp AT TIME ZONE 'America/New_York'; This treats '2024-06-01 12:00:00' as New York time and converts it to UTC timestamp with time zone.

Result

The output is a timestamptz value representing the same moment in UTC.

This step shows how AT TIME ZONE assigns a time zone to a naive timestamp and converts it to an absolute time.

4

Intermediate

Using AT TIME ZONE with timestamp with time zone

🤔Before reading on: do you think AT TIME ZONE changes the stored moment or just the displayed time when used on timestamptz? Commit to your answer.

Concept: When used on timestamptz, AT TIME ZONE converts the timestamp to the given zone and returns a timestamp without time zone.

Example: SELECT now() AT TIME ZONE 'UTC'; This converts the current timestamptz to UTC time but returns it as timestamp without time zone (local time in UTC).

Result

You get a timestamp without time zone showing the local time in the specified zone.

This shows that AT TIME ZONE can strip time zone info by converting to local time in a zone.

5

Intermediate

Chaining AT TIME ZONE for conversions

🤔Before reading on: can you convert a timestamp from one zone to another by chaining AT TIME ZONE twice? Commit to your answer.

Concept: You can convert between two time zones by applying AT TIME ZONE twice, switching between timestamptz and timestamp without time zone.

Example: SELECT '2024-06-01 12:00:00'::timestamp AT TIME ZONE 'America/New_York' AT TIME ZONE 'Europe/London'; This converts New York time to UTC, then converts UTC to London local time.

Result

You get a timestamp without time zone showing the time in London corresponding to the original New York time.

Knowing how to chain AT TIME ZONE lets you convert times between any zones precisely.

6

Advanced

Handling Daylight Saving Time with AT TIME ZONE

🤔Before reading on: do you think AT TIME ZONE automatically adjusts for daylight saving time? Commit to your answer.

Concept: AT TIME ZONE respects daylight saving rules of the specified zone when converting times.

Example: SELECT '2024-03-10 02:30:00'::timestamp AT TIME ZONE 'America/New_York'; This time falls in the daylight saving transition. PostgreSQL adjusts the offset accordingly.

Result

The output reflects the correct UTC time considering daylight saving shifts.

Understanding daylight saving handling prevents errors during time changes in real applications.

7

Expert

Surprising Behavior with AT TIME ZONE and Timestamps

🤔Before reading on: do you think AT TIME ZONE always returns the same data type it receives? Commit to your answer.

Concept: AT TIME ZONE changes the data type: timestamp without time zone becomes timestamptz, and timestamptz becomes timestamp without time zone.

This means the function both converts the time and flips the type, which can confuse queries expecting one type. For example, SELECT '2024-06-01 12:00:00'::timestamp AT TIME ZONE 'UTC'; returns timestamptz, but SELECT now() AT TIME ZONE 'UTC'; returns timestamp without time zone.

Result

You must be careful with type expectations when using AT TIME ZONE in queries.

Knowing this type flip avoids bugs and helps write correct queries that handle time zones properly.

Under the Hood

PostgreSQL stores timestamptz internally as UTC. When you use AT TIME ZONE on timestamp without time zone, it assumes the timestamp is in the given zone and converts it to UTC (timestamptz). When used on timestamptz, it converts the UTC time to the target zone's local time and returns it as timestamp without time zone. This dual behavior means AT TIME ZONE acts as both a converter and a type transformer.

Why designed this way?

This design allows flexible conversions between naive and aware timestamps without extra functions. It leverages PostgreSQL's internal UTC storage for timestamptz and the need to represent local times as timestamp without time zone. Alternatives could have been separate functions, but this unified syntax is concise and expressive.

┌─────────────────────────────┐
│ timestamp without time zone  │
│ (naive local time)           │
└──────────────┬──────────────┘
               │ AT TIME ZONE 'zone'
               ▼
┌─────────────────────────────┐
│ timestamp with time zone     │
│ (UTC internally)             │
└──────────────┬──────────────┘
               │ AT TIME ZONE 'zone'
               ▼
┌─────────────────────────────┐
│ timestamp without time zone  │
│ (local time in new zone)     │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does AT TIME ZONE always keep the same data type it receives? Commit to yes or no.

Common Belief: AT TIME ZONE just changes the displayed time but keeps the data type unchanged.

Reality: AT TIME ZONE changes the data type: timestamp without time zone becomes timestamptz, and timestamptz becomes timestamp without time zone.

Why it matters: Assuming the type stays the same can cause query errors or wrong results when combining timestamps.

Quick: Does AT TIME ZONE ignore daylight saving time when converting? Commit to yes or no.

Common Belief: AT TIME ZONE treats all offsets as fixed and ignores daylight saving time.

Reality: AT TIME ZONE respects daylight saving time rules of the specified zone and adjusts offsets accordingly.

Why it matters: Ignoring daylight saving can cause times to be off by an hour during transitions, leading to scheduling errors.

Quick: If you have a timestamp without time zone, does PostgreSQL know what time zone it is in? Commit to yes or no.

Common Belief: Timestamp without time zone always knows its time zone automatically.

Reality: Timestamp without time zone has no time zone info; it is just a date and time without context.

Why it matters: Assuming it has time zone info can cause wrong conversions and misunderstandings about stored times.

Quick: Can you convert directly between two time zones with a single AT TIME ZONE call? Commit to yes or no.

Common Belief: One AT TIME ZONE call can convert a timestamp from any zone to any other zone directly.

Reality: You need to chain two AT TIME ZONE calls to convert between two different zones.

Why it matters: Trying to convert between zones with one call leads to incorrect times and confusion.

Expert Zone

1

AT TIME ZONE flips the timestamp type, which can cause subtle bugs if you expect the same type after conversion.

2

Using named time zones (like 'America/New_York') is better than fixed offsets (like '-05:00') because it handles daylight saving automatically.

3

The session time zone setting affects how timestamptz values are displayed but not how they are stored or converted internally.

When NOT to use

Avoid using AT TIME ZONE when you need to store local times without any time zone context; use timestamp without time zone directly. For complex time zone arithmetic or historical time zone data, consider specialized libraries or application logic.

Production Patterns

In production, AT TIME ZONE is used to normalize user input times to UTC for storage, then convert UTC times back to user local times for display. It is also used in reporting to show times in different zones and in scheduling systems to handle events across zones.

Connections

Unix Epoch Time

builds-on

Understanding how PostgreSQL converts times to UTC internally relates to Unix epoch time, which counts seconds from a fixed point in UTC.

Internationalization (i18n)

builds-on

Handling time zones correctly is a key part of internationalization, ensuring software works properly for users worldwide.

Relativity of Time in Physics

opposite

While physics shows time depends on observer motion and gravity, databases simplify time to fixed zones and UTC for practical consistency.

Common Pitfalls

#1 Confusing timestamp without time zone as having time zone info.

Wrong approach:

SELECT '2024-06-01 12:00:00'::timestamp + interval '1 hour';

Correct approach:

SELECT ('2024-06-01 12:00:00'::timestamp AT TIME ZONE 'America/New_York') + interval '1 hour';

Root cause:

Timestamp without time zone is naive; adding intervals without considering time zone can produce wrong absolute times.

#2 Using AT TIME ZONE once to convert between two different zones.

Wrong approach:

SELECT '2024-06-01 12:00:00'::timestamp AT TIME ZONE 'Europe/London';

Correct approach:

SELECT '2024-06-01 12:00:00'::timestamp AT TIME ZONE 'America/New_York' AT TIME ZONE 'Europe/London';

Root cause:

One AT TIME ZONE call only converts between timestamp and timestamptz, not between two zones directly.

#3 Ignoring daylight saving time when converting times.

Wrong approach:

SELECT '2024-03-10 02:30:00'::timestamp AT TIME ZONE 'EST';

Correct approach:

SELECT '2024-03-10 02:30:00'::timestamp AT TIME ZONE 'America/New_York';

Root cause:

Using fixed offset zones like 'EST' ignores daylight saving, causing incorrect conversions.

Key Takeaways

PostgreSQL has two timestamp types: with and without time zone, which behave differently.

AT TIME ZONE converts timestamps between zones and flips the timestamp type between with and without time zone.

Proper use of AT TIME ZONE respects daylight saving time and ensures correct absolute time representation.

Chaining AT TIME ZONE calls allows conversion between any two time zones accurately.

Misunderstanding time zone handling leads to common bugs in scheduling, logging, and data analysis.