Cookbook recipe

Safe major-version upgrade with pg_upgrade

Applies to PostgreSQL 13–17 Last reviewed May 2026 Grounded in source

What This Is

A production experience capsule based on real incident patterns.

Why It Matters

Builds production judgment under pressure.

Next Step

Run the decision point → · Enter full simulator →

Estimated investigation4 min

Scenario

You are moving from PostgreSQL 14 to 17. pg_upgrade migrates the cluster in place far faster than dump/restore. Diagnose it Run the compatibility check first: pg_upgrade --check -b /old/bin -B /new/bin -d /old/data -D /new/data Why…

Investigation Path

You are moving from PostgreSQL 14 to 17. pg_upgrade migrates the cluster in place far faster than dump/restore.

Diagnose it

Run the compatibility check first:

pg_upgrade --check 
  -b /old/bin -B /new/bin 
  -d /old/data -D /new/data

Why it happens

pg_upgrade relinks catalogs to the new binaries; with --link it hard-links data files for a near-instant upgrade instead of copying. The --check pass validates compatibility before any change.

This is a Pro lesson

Get every Learning Pathway and cookbook recipe — grounded in PostgreSQL source code, with diagnostics, fixes, and prevention for each topic.

Continue this lesson to learn:

  • How to fix it
  • Prevent it next time
  • Related & next steps
  • All 36 Learning Pathway lessons
  • 170+ cookbook recipes
  • Source-grounded diagnostics & fixes
Unlock everything — $24.99/month $199/year — save 35%

Secure checkout Cancel anytime Source-grounded

Career Impact

This scenario builds production judgment and operational confidence under pressure.

Open Career Dashboard →

Keep going

Related & next steps

More like this

effective_cache_size Set Too Low: Planner Avoids Index Scans Fix bad row estimates with extended statistics One Tuple at a Time: How the Volcano Executor Runs Your Plan pg_basebackup Failure Connection pooling with PgBouncer (transaction vs session)
Browse the cookbook Step-by-step recipes Follow a pathway Learn it in order Open the glossary Every concept, plainly
Was this helpful?

← All cookbook recipes