Major Releases, Minor Releases, Support Policy, Compatibility, and Upgrade Planning

Learning outcomes

Suppose ServiceHub is running well on PostgreSQL 18 and an administrator sees two different notices: one announces a new PostgreSQL 18 maintenance release, while another announces a PostgreSQL 19 beta. Treating both as “new versions” would produce very different operational decisions. A minor update inside major version 18 preserves the PostgreSQL on-disk storage format; moving from major 18 to major 19 is a major-version migration with compatibility work and a different rollback story.

PostgreSQL’s release model is deliberately predictable, but production planning still requires evidence. You need to know which server is running, which client and tools are installed, which extensions and drivers depend on the major version, when support ends, and whether application behavior has changed.

1. Version numbers since PostgreSQL 10

Starting with PostgreSQL 10, the first number is the major version. In 18.4, for example, 18 is the major version and 4 identifies a minor maintenance release in that major line. A change from 18.x to 19 is therefore a major upgrade. A change from one 18.x maintenance level to a later 18.x maintenance level is a minor update.

Older PostgreSQL releases used a three-part convention, which is why old documentation may talk about a “major version” such as 9.6 and a minor release such as 9.6.24. Do not apply that historical numbering rule to modern releases.

SHOW server_version;SHOW server_version_num;SELECT version();

server_version is human-readable. server_version_num is useful when software needs a comparable integer representation, but application code should still avoid making unsupported assumptions about features solely from a number. Extension availability, configuration, privileges, and provider restrictions can matter too.

psql --versionpg_dump --versionpg_restore --version

Those commands report client-tool binaries on the machine where they run. They do not prove the remote server’s version. This separation becomes especially important during major upgrades, where the version of pg_dump, pg_restore, and pg_upgrade matters.

2. Major releases deliver features; minor releases deliver fixes

The PostgreSQL Global Development Group normally publishes a new major version about once a year. Major versions introduce new features and can change behavior or compatibility. Each major is then maintained with bug fixes and, when necessary, security fixes through minor releases. The project targets at least quarterly minor releases and may publish an out-of-cycle update when an important fix should not wait.

A minor release is not “optional because it has no features.” PostgreSQL security fixes are delivered in minor updates, and the project recommends running the latest minor release available for the chosen supported major. Production teams still apply their normal change-management and validation process because any binary change deserves an operational check.

3. Five years of support is a planning boundary

Each PostgreSQL major version is supported for five years after its initial release. At end of life, the project stops publishing fixes for that major. That means an organization should not wait for the final supported day before designing its next upgrade. Extensions, operating-system packages, drivers, managed services, and internal certification cycles may impose earlier practical deadlines.

These dates are planning evidence, not permanent constants. The live PostgreSQL Versioning Policy page is authoritative. Future readers should re-check it because this lesson is a snapshot reviewed in August 2026.

4. Why minor updates are operationally simpler

PostgreSQL minor releases within one major line keep the internal storage format compatible. That means a minor update does not require a logical dump/reload or pg_upgrade simply because the patch number changed. Package managers or installers typically replace binaries and restart the server according to the local distribution’s procedure.

“Storage-compatible” does not mean “zero work.” Read the release notes, take or verify a recovery point appropriate to the service, confirm replication/topology compatibility, patch replicas and primaries in a safe order for your architecture, restart when required, and run application smoke tests. If an extension ships native libraries, it can have its own package update and restart requirements.

SELECT version() AS server_build;SELECT current_database(), current_user;SELECT extname, extversionFROM pg_catalog.pg_extensionORDER BY extname;SELECT name, setting, source, pending_restartFROM pg_catalog.pg_settingsWHERE name IN ('shared_preload_libraries', 'wal_level', 'max_connections')ORDER BY name;

Save comparable output after the update. This does not replace full testing, but it gives you an auditable before/after identity record instead of the weak statement “the service came back up.”

5. Major upgrades cross a physical compatibility boundary

A PostgreSQL major upgrade may change the internal representation of database data. The supported migration families are therefore explicit: logical dump/restore, pg_upgrade, or replication-based approaches where appropriate. Which path is best depends on database size, downtime budget, operating-system/platform changes, extension support, rollback requirements, and topology.

Never stop PostgreSQL 18, install PostgreSQL 19, and point the 19 server directly at the old 18 PGDATA as though it were a minor update. The server checks the data directory’s major-version identity and refuses an incompatible directory rather than silently interpreting it as a newer format.

WRONG MENTAL MODEL1. Stop PostgreSQL 18.2. Replace the postgres executable with PostgreSQL 19.3. Start PostgreSQL 19 against the PostgreSQL 18 data directory.4. Hope the files are upgraded in place.SAFER MODELChoose and rehearse a supported migration method:- pg_upgrade- logical dump/restore- replication-based migration where the source/target combination supports itThen validate extensions, statistics, application behavior, and rollback/cutover plans.

Do not perform the wrong sequence merely to see the error. The lesson is about recognizing the unsupported plan before touching real data.

6. Compatibility has more than one layer

An upgrade can be physically valid and still break an application. PostgreSQL production planning needs several compatibility layers:

This is why “PostgreSQL upgraded successfully” should mean more than a green service status. The database must be correct, the application must work, and the recovery path must still be credible.

7. Inventory extensions before planning a target major

Extensions are database-local installations backed by server-visible extension packages. A major upgrade cannot assume that every package from the source major is already installed for the target major.

SELECT e.extname,       e.extversion AS installed_version,       a.default_version AS available_default_versionFROM pg_catalog.pg_extension AS eLEFT JOIN pg_catalog.pg_available_extensions AS a  ON a.name = e.extnameORDER BY e.extname;SELECT name, version, installed, superuser, trustedFROM pg_catalog.pg_available_extension_versionsORDER BY name, version;

The second query can return a long list. The point is not to install everything. It is to make extension dependencies explicit so the target environment can be built and tested before cutover.

8. Client/server version differences: observe before assuming

psql and libpq are clients. They can connect over the PostgreSQL protocol to servers that are not the exact same maintenance release, and often not the same major release, but that does not make every client-side meta-command or administrative utility interchangeable across arbitrary versions. Backup/restore and major-upgrade tooling have stricter documented rules than a simple interactive query session.

psql --versionpg_dump --versionpg_restore --versionpg_isready --version

SHOW server_version;SHOW server_version_num;SELECT version();

When troubleshooting, always say which side a version belongs to: “psql 18.x client connecting to PostgreSQL 18.x server,” rather than “we are on 18” with no component named.

9. A deliberately wrong approach: “latest means safest for production”

During a beta cycle, the largest version number visible on the PostgreSQL website can belong to a pre-release major. Beta and release-candidate builds exist so users and ecosystem developers can test upcoming behavior. They are not intended as production releases.

The repair is to choose a supported stable major, run its current patched minor release, and test the next major separately. For this chapter, that means PostgreSQL 18.x is the reproducible stable-major baseline while PostgreSQL 19 pre-release builds belong only in disposable compatibility experiments until general availability.

10. Hands-on lab: build a version and upgrade-readiness record

This lab changes nothing. Run it against a disposable PostgreSQL 18.x instance and save the result as a text artifact for future upgrade comparison.

Step 1 — server identity

SELECT now() AS observed_at,       version() AS server_build,       current_database() AS database_name,       current_user AS effective_role;SHOW server_version;SHOW server_version_num;SHOW data_directory;SHOW data_checksums;

Step 2 — installed database extensions

SELECT extname, extversionFROM pg_catalog.pg_extensionORDER BY extname;

Step 3 — client tools

psql --versionpg_dump --versionpg_restore --version

Step 4 — create a compatibility worksheet

Verification checklist

• You can state server and psql versions separately.
• You know whether the contemplated change is minor or major.
• You have listed installed extensions rather than assuming none exist.
• You can point to official release notes/support policy for the chosen target.
• You have a rollback or recovery strategy appropriate to the change class.

11. Summary and bridge to installation

PostgreSQL releases a new major roughly annually and maintains each major for five years with minor bug/security updates. Since PostgreSQL 10, a number such as 18.4 means major 18, minor 4. Minor updates stay within one physical storage format; major upgrades cross a compatibility boundary and require a supported migration technique.

Version planning is multi-layered: server binaries, data directory, psql/libpq and utilities, extensions, drivers, application SQL, and operational tooling all deserve explicit evidence. The next lesson turns that policy into a reproducible local environment by installing PostgreSQL 18.x on Windows, Linux, or Docker and verifying a real initialized database cluster.

Authoritative references

• PostgreSQL Versioning Policy
• PostgreSQL Release Roadmap
• PostgreSQL Beta Information
• PostgreSQL Release Notes Archive
• Upgrading a PostgreSQL Cluster
• PostgreSQL Security Information