Minor version upgrades · PostgreSQL

Minor upgrades — 18.5 to 18.6 — are the cheapest maintenance PostgreSQL offers and the most frequently deferred.

What a minor release is

The version is major.minor: in 18.6, 18 is the major version and 6 is the minor. Minor releases contain security fixes, bug fixes and data-corruption fixes. They contain no new features and no on-disk format changes.

That last part is the whole reason the procedure is short: the data directory written by 18.5 is the data directory 18.6 reads. There is nothing to convert.

The procedure

# 1. Read the release notes for every version you are skipping.
#    This is the step that is skipped and the one that matters.

# 2. Stop the cluster cleanly.
pg_ctl -D $PGDATA stop -m fast

# 3. Replace the binaries (package manager).
apt-get install --only-upgrade postgresql-18

# 4. Start.
pg_ctl -D $PGDATA start

# 5. Verify.
psql -c "SELECT version();"

Downtime is a fast shutdown plus a startup — lesson XII-07 measured a fast shutdown at 119 ms on a small cluster, and startup is dominated by whatever crash recovery is needed, which after a clean shutdown is none.

Why they get deferred, and why that is a mistake

The reasons are always the same: it needs a restart, nothing is obviously broken, and there is no new feature to want.

Against that:

Minor releases contain security fixes, published with the release. Not applying them is a decision to run known-vulnerable software.
They contain data-corruption fixes. Some of the most serious PostgreSQL bugs have been silent corruption fixed in a minor release.
The community supports only the latest minor version. A bug report against 18.2 is answered with “upgrade to the current minor first”.
They accumulate. Six deferred minor upgrades is not six times the risk of one; it is one upgrade with six releases of changes in it and correspondingly more release notes nobody read.

The exception that requires action

The rule “minor upgrades need no data change” has one class of exception, and it is why the release notes must actually be read.

Occasionally a minor release fixes a bug that produced incorrect data or corrupt indexes. Installing the fix stops it happening again; it does not repair what already happened. Such releases say so explicitly, with instructions — typically to REINDEX affected indexes, or to check for affected rows.

A team that upgrades without reading has installed the fix and kept the damage, and will conclude the fix did not work.

The release notes for each minor version have a short “Migration to Version X.Y” section at the top. It is usually one line saying no action is required. When it is not, it names exactly what to do.

Read that section for every version you are skipping, not just the one you are moving to.

Verifying

SELECT version();
SELECT count(*) FROM pg_stat_replication;   -- on the primary
SELECT pg_is_in_recovery();                 -- on each standby

And check the log for anything unexpected on startup. A minor upgrade that went wrong usually says so immediately — a missing library, a version mismatch between the binaries and the data directory — rather than failing subtly later.

What is actually pinned to the major version, and the mismatch that bites

The catalogue version number in pg_control identifies the on-disk format, and it changes only between major versions. That is what makes a minor upgrade a binary swap.

But several other things are tied to the major version, and they are where minor upgrades go wrong in practice — not in the database, but around it.

Extension shared libraries are built per major version and live in a version-specific directory. A package manager upgrading postgresql-18 without upgrading postgresql-18-postgis can leave a library the server cannot load, and the failure appears when a query touches that extension rather than at startup.

Client libraries are independent. libpq from any recent version talks to any recent server, so upgrading the server does not require touching clients. This is genuinely one less thing to coordinate.

The package layout matters more than the database does. On Debian, postgresql-18 and postgresql-client-18 are separate packages, and pg_ctlcluster manages clusters through postgresql-common. An upgrade that installs binaries but leaves a cluster running the old ones — which happens when the package restarts nothing and nobody notices — produces a cluster that is running 18.5 while psql --version reports 18.6.

That last one is worth checking explicitly, because SELECT version() reports what the running server is, and the running server is the old one until it is restarted:

-- what the server is running, not what is installed
SELECT version();

The discrepancy between an installed version and a running version is the most common way a minor upgrade is believed to have happened and has not, and it survives until the next unrelated restart quietly applies it.

What to take from this

Minor releases change no on-disk format. Stop, swap binaries, start.
Downtime is a shutdown plus a startup.
Standbys first, primary last. A newer standby is supported; a newer primary is not.
Minor releases carry security and data-corruption fixes, and only the latest minor version is supported.
Read the “Migration to Version X.Y” section for every version you skip. Occasionally a fix requires a REINDEX you must do yourself.
Verify with SELECT version() — it reports the running server, and a cluster that was not restarted is still on the old one.

Cross-course references

Linux for Production Sysadmins — Part XI (Package management), Part XXXII (Vulnerability and patch management) and Part XXXIII (Fleet patch management) cover the patching cadence this fits into, including the restart that a package update does not perform.
Ansible for Production Sysadmins — Part XL (Patch and reboot management) and Part XXXI (Serial execution) cover upgrading an estate one node at a time, standbys first.