I learned all of this the hard way, so let me start there.

How I learned this

When we started, we saved times the simple way: the local time someone typed, with no timezone attached. For example 2026-12-05 10:00.

It looked fine. Then it broke quietly:

• Courses closed an hour early, or an hour late.
• Early-bird prices ended at the wrong moment.
• A page showed a different time from the one that was saved.

The cause was the same every time. 2026-12-05 10:00 is not a moment. It's 10:00 somewhere. Without the "where", every server, browser and job read it in its own timezone, and they didn't agree.

So I read the official sources, asked a lot of questions, and we changed how we store time. Here is what I wish someone had told me on day one.

Step 1: a moment and a wall clock are two different things

• A moment is one point in time, the same everywhere on Earth. "When the rocket launched."
• A wall-clock time is what a clock on the wall shows in one place. "10:00 in Vancouver."

The same moment shows different wall-clock times in different places. 10:00 in Vancouver is 22:30 in Bengaluru on the same moment.

Bugs happen when you save a wall-clock time and treat it like a moment.

Step 2: UTC is the reference clock

UTC (Coordinated Universal Time) is the world's reference clock. It never changes for daylight saving. Every place on Earth is described as "UTC plus or minus some hours" at a given moment:

If you save every moment in UTC, every server, browser and background job reads the same value. That fixes the "which timezone did this mean?" problem at the root.

Step 3: save the place by name, never by offset

An offset like −07:00 is a number. A timezone name like America/Vancouver is a place with a history of rules.

Offsets change. Dublin is +00:00 in January and +01:00 in July. Vancouver was −08:00 every winter until 2026. If you save −08:00, you've saved a fact that was true for one date only.

If you save America/Vancouver, the software works out the right offset for any date: past, present or future, daylight saving included. You write no daylight-saving code at all.

Names look like Continent/City: America/Vancouver, America/Edmonton, Europe/Dublin, Asia/Kolkata. (Note: it's Asia/Kolkata and Europe/Dublin, not "India/Calcutta" or "Ireland/Dublin". Use the official list.)

Step 4: who keeps these rules? The IANA timezone database

Somebody has to record that "Vancouver stopped changing clocks in 2026". That somebody is the IANA Time Zone Database (also called tzdata or the Olson database), a small group of volunteers who publish the rules for every place on Earth, going back decades.

When a government changes its clocks, the database ships a new release. Operating systems, Java, Postgres, Node.js and libraries like moment-timezone copy that data into themselves.

That last part matters: the timezone database is a dependency, like any library. If you don't update it, your app uses old rules.

And you probably have more than one copy:

• the server's operating system,
• your runtime (Node.js, Java),
• your date library (moment-timezone bundles its own),
• your database (Postgres ships its own copy unless it was built to use the system's),
• every user's browser.

They can disagree for weeks after a change.

Step 5: what changed in Canada in 2026 (a real example)

This year four parts of Canada stopped changing their clocks. The database needed four releases to keep up:

British Columbia moved its clocks forward for the last time on 8 March 2026. On 1 November, when clocks would normally go back, they stayed put.

Why Vancouver now shows "MST"

Short labels like PST and MST are not decoration. Each one names an offset:

Vancouver is now at UTC−7 all year, with no daylight saving. PST would be an hour wrong. PDT would say daylight saving is on, and it no longer exists there. So the database labels it MST, the long-standing name for UTC−7 standard time in North America. For the same reason, Edmonton (now UTC−6 all year) is labelled CST.

Two honest notes:

• The provinces use their own names: British Columbia calls it "Pacific Time" (PCT), Alberta calls it "Alberta Time". The database's 2026b notes say a future release may change the label.
• Windows and browsers don't always show the database's label. Browsers use another project (Unicode CLDR) for display names, so you may see "GMT-7" or a long name instead.

Our choice was to show what the database says. If the database changes the label later, our screens change with the next update, with no code. If you override labels by hand, you own that list forever. And never search-and-replace "MST" with something else: Arizona really is MST all year, and so is Denver in winter.

Step 6: what this looks like in code

In the database (Postgres): use timestamptz for moments, and keep the zone name next to it.

CREATE TABLE course (
  id         bigint PRIMARY KEY,
  starts_at  timestamptz NOT NULL,  -- a moment; Postgres stores it as UTC
  time_zone  text        NOT NULL   -- IANA name, e.g. 'America/Vancouver'
);

-- Show it as the local wall-clock time of the course's place
SELECT starts_at AT TIME ZONE time_zone AS local_start
FROM course;

Despite its name, timestamptz doesn't store a timezone. It stores the moment in UTC and converts it for display using your session's TimeZone setting. The plain timestamp type (without time zone) is the "local time with no zone" trap from the start of this guide.

In JavaScript: a Date is already a moment (milliseconds since 1970 in UTC). Convert only when you display it.

const startsAt = new Date('2026-12-05T17:00:00Z'); // the moment, from the API, in UTC

startsAt.toLocaleString('en-CA', {
  timeZone: 'America/Vancouver', // the place, by name
  dateStyle: 'medium',
  timeStyle: 'short',
});
// 10:00 a.m. on 5 Dec 2026 in Vancouver (with up-to-date timezone data)

In background jobs: schedule in UTC. "Close this course at 2026-12-05T17:00:00Z" fires at the right moment whether the course is in Vancouver, Dublin or Bengaluru. Our job queue only ever deals in UTC, and that removed a whole class of bugs.

Step 7: the one case where UTC alone breaks: future events

Here's the trap that almost nobody mentions in beginner guides.

Say in February 2026 someone creates an event: 10:00 on 5 December 2026, in Vancouver. At that time the rules said Vancouver would be at UTC−8 in December. So the app saved 2026-12-05T18:00:00Z.

Then British Columbia changed its law. Vancouver will be at UTC−7 in December instead. Now that saved moment, 18:00Z, shows as 11:00 in Vancouver. The event is an hour off, and nobody touched it.

The person meant "10:00 on the wall clock in Vancouver". We saved a moment computed with rules that later changed.

What to do about it:

• For things that already happened (payments, logins, check-ins): UTC is exactly right. The past doesn't change.
• For future events people plan by the wall clock (a class at 10:00 local): also keep the local time and the zone name the person chose, and recompute the UTC moment from them when the rules change. Or at least check future events after every timezone-data update.

Jon Skeet wrote the classic piece on this: Storing UTC is not a silver bullet (link at the end). Read it once you're comfortable with the basics.

A checklist to keep

1. Save moments in UTC (timestamptz in Postgres, ISO strings ending in Z in APIs).
2. Save the place as an IANA name (America/Vancouver), never as an offset.
3. Convert to local time only at the last step, when a person reads it.
4. Schedule jobs in UTC.
5. Treat the timezone database as a dependency: update it, and know every copy you run.
6. For future wall-clock events, keep the local time + zone name too, and re-check after rule changes.
7. Show the label the database gives you. Don't hand-edit labels.

What I'd tell a new developer

UTC tells you when. The zone name tells you where. You need both, and the local time is something you work out at the end, not something you store.

What's the one timezone rule you wish someone had told you earlier?

Sources

• IANA Time Zone Database: https://www.iana.org/time-zones
• 2026b release notes (British Columbia, the "MST" label): https://www.iana.org/time-zones/releases/2026b
• 2026c release notes (Alberta, "CST"): https://www.iana.org/time-zones/releases/2026c
• 2026e release notes (Manitoba): https://www.iana.org/time-zones/releases/2026e
• Time in British Columbia (PCT name, dates): https://en.wikipedia.org/wiki/Time_in_British_Columbia
• moment-timezone issue #1163 (2026 Canadian changes): https://github.com/moment/moment-timezone/issues/1163
• PostgreSQL date/time types: https://www.postgresql.org/docs/current/datatype-datetime.html
• Jon Skeet, Storing UTC is not a silver bullet (2019): https://codeblog.jonskeet.uk/2019/03/27/storing-utc-is-not-a-silver-bullet/

Who this is for: anyone who has seen a Postgres query that should be fast but isn't, and EXPLAIN shows a bad plan without saying why. You don't need to know planner internals. Everything is explained from zero, with the real code lines.

The short version: in Postgres 15 and every version released so far, the planner splits your joins into groups before it removes the joins it doesn't need. If the two tables that need an index lookup land in different groups, the fast plan can't be built at all. join_collapse_limit sets the group size, and the "safe" values are not a range: they have holes. Postgres 16+ gets a change that helps, but doesn't remove the problem completely.

1. The problem

A report on the platform I work on started timing out. One query, run with a few filters, took 137,779 ms: more than two minutes.

The query reads from a view. That view is built on other views, which are built on more views (we call them layered views). It looks like one simple SELECT ... FROM report_view WHERE .... Underneath, it is not simple at all.

EXPLAIN ANALYZE showed the slow part clearly:

Nested Loop  (rows=1) (actual time=1112..139689 rows=1005)
  Join Filter: (enrollment.course_id = course.id)
  Rows Removed by Join Filter: 8,944,739
  ->  Bitmap Heap Scan on course             (estimated rows=1, actual rows=181)
  ->  Hash Left Join ...                     (loops=181)
        ->  Hash (rows=895194) (actual time=538.801) loops=181     ← 538.8 ms × 181 = 97.5 s

Two things were wrong at once:

1. The plan shape. Postgres built both sides of the join completely, then compared them row by row (Join Filter) and threw away 8.9 million rows. The fast way would have been: take each of the 181 courses and look up its enrollments through an index. In a plan that looks like Index Cond: (course_id = course.id).
2. The row estimate. Postgres expected 1 course and got 181. It planned an expensive inner step thinking it would run once. It ran 181 times.

Fixing the plan shape alone was enough: the inner step drops to ~0.06 ms, so running it 181 times stops mattering. The rest of this article is about the plan shape, because that's the part EXPLAIN can't explain.

2. The first fix worked, and that was the problem

The first suggestion I got (from an AI assistant) was to raise one planner setting, join_collapse_limit. It worked. The report became fast.

But I didn't know why it worked, so I tested every value from 8 to 140, three times each, on a copy of real data:

 8 10 12 14 16 18 20 22 24 26 28 30 32 34 ............ 140
 ✗  ✗  ✓  ✗  ✓  ✓  ✓  ✓  ✓  ✗  ✗  ✓  ✗  ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

At 32 the query took 140,611 ms. At 34 it took 23.9 ms. That's almost 6,000× from changing one number by two.

This is not a threshold. It's a range with holes in it. If the setting were simply "bigger is better", 14 couldn't be slow when 12 is fast. Nobody could tell me why, so I went to the Postgres source code.

3. Background: what the planner does with your joins (two minutes)

3.1 Views disappear

A view is saved SQL. When you query a view, Postgres pastes the view's SQL into your query before planning. Views built on views get pasted recursively. Our one-line query became about 435 table references: one inner view alone contributed 121, and it appeared three times.

3.2 Postgres can throw away useless LEFT JOINs ("join removal")

Most of those 435 tables aren't needed for this report. Postgres can remove a LEFT JOIN if all of these are true (join_is_removable, src/backend/optimizer/plan/analyzejoins.c:159 in 15.8):

1. It's a LEFT join.
2. The right side is one single table.
3. That table can match at most one row, proven by a primary key or unique index on the join columns.
4. No column of that table is used anywhere above the join: SELECT, WHERE, ORDER BY, or another join's ON.

If all four hold, removing the table can't change the result, so Postgres drops it. In our query, removal cut ~435 references down to about 11.

Rule 4 is why the columns you select matter. With 2 columns selected, only 3 tables survived and the query was fast at the default settings. With the report's 27 columns, 10–11 survived and it was slow. Each extra column can bring back a table that would otherwise be removed.

3.3 Postgres limits how hard it searches

To join N tables, the planner tries different orders. The number of possible orders grows like N!:

So Postgres protects itself with two settings:

• join_collapse_limit (default 8): tables written with explicit JOIN syntax are grouped into lists of at most this many items. The planner searches join orders inside each list, and treats each finished list as one fixed piece.
• geqo_threshold (default 12): if a single list has 12 or more items, Postgres stops searching exhaustively and uses GEQO, a genetic (randomised) optimiser. Plans can then change from run to run.

4. The real cause: the order of two steps

Here is the order inside the planner's main function, query_planner(), in Postgres 15.8 (src/backend/optimizer/plan/planmain.c):

The join list is built at line 184, counting all ~435 tables. The useless ones are removed at line 221, and the join list is never rebuilt. That's the whole problem.

4.1 How the join list is built

deconstruct_recurse visits the join tree bottom-up. At every JOIN it has the list from the left side and the list from the right side, and applies one rule (src/backend/optimizer/plan/initsplan.c:1037-1058):

else if (list_length(leftjoinlist) + list_length(rightjoinlist) <=
         join_collapse_limit)
{
    /* OK to combine subproblems */
    joinlist = list_concat(leftjoinlist, rightjoinlist);
}
else
{
    /* can't combine, but needn't force join order above here */
    ...
    joinlist = list_make2(leftpart, rightpart);
}

In plain words:

• left items + right items ≤ limit → merge them into one flat list (all orders will be tried across them);
• otherwise → don't merge; return exactly two items, the left side as a sub-list and the right side.

A tiny example. A JOIN B JOIN C with a limit of 2 (Postgres reads it as (A JOIN B) JOIN C):

The result [[A, B], C] means: plan A+B together first, on their own; then join that finished piece with C. The order "A with C first" is never even considered.

4.2 Why a sub-list blocks the fast plan

When the planner meets a sub-list, it plans it completely and alone first (make_rel_from_joinlist, src/backend/optimizer/path/allpaths.c:3325). The level above gets one finished result and can't look inside it.

The fast plan we wanted is "for each course, use an index to find its enrollments". Postgres calls this a parameterized nested loop. It only works when both tables are in the same list. If enrollment sits inside a sub-list and course sits outside it, that lookup can't be built. Postgres isn't choosing the slow plan because it thinks it's cheaper. The fast plan doesn't exist as an option.

4.3 Removal doesn't fix the shape

When remove_useless_joins removes a table, it deletes that table's entry from the join list (remove_rel_from_joinlist, analyzejoins.c:462). A sub-list stays a sub-list:

sublist = remove_rel_from_joinlist((List *) jlnode, relid, nremoved);
/* Avoid including empty sub-lists in the result */
if (sublist)
    result = lappend(result, sublist);

So the borders drawn while ~435 tables were counted survive, even though only ~11 tables remain. At the default limit of 8, course and enrollment ended up on different sides of a border.

Postgres's own code admits the order is a compromise. This comment sits right above the removal call:

/*
 * Remove any useless outer joins.  Ideally this would be done during
 * jointree preprocessing, but the necessary information isn't available
 * until we've built baserel data structures and classified qual clauses.
 */

In other words: the facts needed to decide "this join is useless" are collected in the same walk that builds the join list. So by the time Postgres knows what's useless, the groups are already drawn.

5. Seeing it happen: I added logging inside the planner

Reading the code told me what could happen. To see what did happen, I compiled PostgreSQL 15.8 from the official source and added log lines inside deconstruct_recurse (every JOIN decision) and make_rel_from_joinlist (every final list):

elog(NOTICE, "JOIN|right=%s|L=%d|R=%d|sum=%d|jcl=%d|act=%s", ...);

I loaded a schema-only copy of the database (tables, views, and all 270 primary keys and unique constraints, no rows) and ran the report query.

Tip: the constraints matter. My first copy had no primary keys, so Postgres couldn't prove any join was useless, nothing was removed, and the trace showed 766 join-list entries instead of 45. An experiment without unique constraints measures the wrong tree.

What came out, per run:

Same 739 decisions either way. The limit turned 83 cuts into 9, and that's the whole difference.

At limit 8, the top of the tree showed three cuts, each just over the limit:

  L +  R  =  sum   vs 8   ->  decision
  7 +  4  =  11    vs 8   ->  refuse    <-- cut
  8 +  2  =  10    vs 8   ->  refuse    <-- cut
  6 +  3  =   9    vs 8   ->  refuse    <-- cut

At limit 64, the decisive JOIN merged two halves of the query, one of 34 table references and one of 30:

 34 + 30  =  64    vs 64  ->  MERGE     <-- the merge that puts course and enrollment together

34 + 30 = 64, against a limit of exactly 64. It passes by a margin of zero.

5.1 Why the safe values have holes

Look at what each decision returns:

• a merge returns a list of length L + R (it gets longer);
• a refusal returns a list of length 2 (it gets shorter).

So a merge that succeeds low in the tree makes a list longer, and that longer list can then fail a check higher up. A refusal low in the tree makes a list shorter, which can then pass higher up. Change the limit and some decisions flip at the bottom, which flips other decisions further up. Whether course and enrollment end up together jumps around as you change the limit. That's the holes: 12 fast, 14 slow, 16 fast.

6. What we shipped, and two traps

6.1 The fix

BEGIN;
SET LOCAL join_collapse_limit = 64;
-- the report query (and its count query)
COMMIT;

137,779 ms → 91 ms.

6.2 Trap 1: bigger is not safer

My own first recommendation was 100. The trace showed that at 100 the tree collapses so far that the biggest single list reaches 12 tables, exactly geqo_threshold, so Postgres switches to the genetic optimiser and plans stop being deterministic. Confirmed on the copy of real data by changing geqo_seed (if the plan changes when the seed changes, GEQO is running):

jcl=48  : no GEQO     jcl=64  : no GEQO     jcl=72 : no GEQO
jcl=80  : no GEQO     jcl=100 : GEQO FIRES

The usable window for this query was 48–80: fast plan, deterministic. 64 sits in the middle of it.

Raising from_collapse_limit as well (the sibling setting for comma-joins and subqueries) didn't help either. It made several values flip from fast to slow. It's a second axis with its own holes.

6.3 Trap 2: never set it globally

A global 64 is dangerous for other queries. In a separate test with a 12-table join where nothing can be removed, join_collapse_limit = 64 made Postgres switch that query to GEQO, while the default of 8 didn't. So:

• set it with SET LOCAL, only in the transaction that runs this query;
• SET LOCAL outside a transaction does nothing: Postgres prints a warning and keeps the old value. Make sure your code really opens a transaction;
• SET LOCAL also resets at COMMIT, so the setting doesn't leak to the next request on a pooled connection.

6.4 Fixes that don't need the setting at all

The setting is a workaround. These fix the cause:

• Select fewer columns in the hot query. Fetching 25 IDs first and then the details for just those 25 ran in 5.5 ms at the default limit, with no planner setting at all.
• Add the unique index that join removal needs. No setting can remove a join Postgres can't prove is unique.
• Fewer view layers in hot paths.

One more honest number: planning alone took about 440 ms for this query, because of view expansion. That's a separate cost, and the setting doesn't touch it.

7. The twist: Postgres changed this in August 2026

On 28 August 2026, Tom Lane committed 2ebf25e7d7, "Perform join removal by editing the query's jointree".

7.1 What it does

Before (15.8 up to the latest released versions):

1. build facts + join list (all tables counted);
2. remove useless joins, patching the planner's notes by hand;
3. plan with the old join list.

After:

1. build facts + join list;
2. remove useless joins by cutting them out of the query tree itself (the LEFT JOIN node is replaced by its left side, analyzejoins.c:399 in master: return j->larg;);
3. throw away all notes and the join list, and start again (goto restart, planmain.c:286 in master);
4. repeat until nothing more can be removed, then plan.

The final join list is built only from the tables that survived. In effect: remove first, then group.

7.2 Why he did it: a bug that returned wrong rows

He didn't do it for speed. He did it because patching the notes by hand kept causing bugs. Bug #19560 is a good example (reported on 19beta2, a regression starting in 16; 15.x is not affected):

CREATE TABLE items (id text, owner text);
CREATE TABLE follows (item_id text, user_id text, UNIQUE (user_id, item_id));
INSERT INTO items VALUES ('item1', 'alice');

WITH viewer AS (SELECT 'bob' AS id)
SELECT count(*) FROM items
LEFT JOIN follows ON follows.item_id = items.id AND follows.user_id = 'bob'
LEFT JOIN viewer ON TRUE
WHERE items.owner = viewer.id;

The only item belongs to alice and the viewer is bob, so the answer is 0. Postgres returned 1. The plan became just Aggregate -> Seq Scan on items: the WHERE condition vanished. follows was removable (a unique key, no columns used), and removing it changed the planner's internal notes so that a new filter should have been created. The filters had already been created earlier, and nothing re-checked them.

Tom's commit message: the old code "implemented the removal by updating those structures in-place … nothing keeps it in step with the rest of the planner", and "We have seen many related bugs over the years too, so it's time to do something drastic."

7.3 Which versions have it (as of 1 November 2026)

7.4 What it does NOT fix

• More survivors than the limit. Our query keeps about 11 tables. 11 > 8, so even on the new code the survivors are split again. In a synthetic test, 6 survivors at limit 8 went from 213–270 ms to 33–36 ms; 11 survivors at limit 8 kept the same bad plan. On 16+ we'd still need the limit at 11 or more.
• Chains cost planning time. Each restart repeats the planning setup. Independent useless joins are all removed in one pass, but a join that only becomes removable after another one is gone waits for the next pass. Views built on views create exactly those chains. Measured by Richard Guo in the discussion of the change:

How long the chains are in real layered-view schemas, and what that costs, hasn't been measured publicly as far as I know.

8. Check your own query in 15 minutes

1. Run EXPLAIN (ANALYZE, BUFFERS). Look for Join Filter on a join you expected to use an index, with a big Rows Removed by Join Filter. Compare with what you'd expect: Index Cond: (child.parent_id = parent.id).
2. Count tables before and after removal. If your query reads from views, count the tables the view expands into (or look at the plan). If far more tables exist in the views than appear in the plan, removal is happening, and the grouping was done on the bigger count.
3. Try a few limits, inside a transaction:

   BEGIN; SET LOCAL join_collapse_limit = 12; EXPLAIN ANALYZE <query>; ROLLBACK;
   

   Test several values, not just one. Expect holes.
4. Check GEQO. Run the plan with two different geqo_seed values. If the plan changes, the genetic optimiser is in play at that limit.
5. Ship it scoped. SET LOCAL inside the transaction of that one query, never globally. Re-test when the views change: our winning merge had a margin of zero.
6. Fix the cause when you can: fewer columns in the hot query, the missing unique index, fewer view layers.

What I'd tell my team

When a tool shows you what is slow but not why, the source code can. Postgres is open, and the comments in the planner are honest about its own compromises. A fix solves one query. Understanding why it works solves the next ten.

Do you build views on top of views in Postgres? How many levels deep did you go before the planner started fighting you?

References (public)

• Postgres commit 2ebf25e7d7: https://github.com/postgres/postgres/commit/2ebf25e7d70a8fce31ace78d723fa9271ab8af72
• Bug #19560 report: https://www.postgresql.org/message-id/19560-54cd7ede78d5e355%40postgresql.org
• Discussion thread: https://www.postgresql.org/message-id/flat/1186816.1784573544%40sss.pgh.pa.us
• PostgreSQL docs, explicit JOIN control and join_collapse_limit: https://www.postgresql.org/docs/current/explicit-joins.html
• PostgreSQL roadmap (release dates): https://www.postgresql.org/developer/roadmap/
• Source files: src/backend/optimizer/plan/planmain.c, initsplan.c, analyzejoins.c, src/backend/optimizer/path/allpaths.c (line numbers from REL_15_8 and master as of 2026-11)