What you should know about PostgreSQL minor upgrades

© Laurenz Albe 2023

The PostgreSQL documentation is rather terse on the subject of minor upgrade. The reason is probably that the procedure is so simple. Still, I find that many people don't understand this topic well, so I thought I should compile the relevant information in an article.

What is a PostgreSQL minor upgrade?

If you look at a PostgreSQL version number like 16.1, it consists of two parts:

• the major version 16
• the minor version 1

(PostgreSQL releases before v10 had three parts: in 9.6.24, “9.6” is the major version and 24 the minor version.) A major upgrade is an upgrade to a higher major version. A minor upgrade is an upgrade to a higher minor version, while the major version stays the same.

Since version numbers have different meanings for different software, let me state the basic properties of a PostgreSQL minor upgrade:

• PostgreSQL minor upgrades contain only bugfixes. There are no new features and no compatibility problems with a minor upgrade.
• PostgreSQL minor upgrades are always binary compatible. To install a minor update, all you have to do is to install the new software and restart PostgreSQL. (On rare occasions, the ABI for an exported PostgreSQL function can change, which may be a problem for some third-party extensions. Check with the vendor of your extension.)
• PostgreSQL minor upgrades won't introduce any new bugs. Well, mostly. We try very hard. If the correct fix for a bug is invasive, we apply that to the development branch and put a “band aid” on the stable versions (“back branches”) that fixes the symptoms without destabilizing the code. However, nothing is perfect, and there have been cases where minor releases introduced new bugs. But this is a rare occurrence; the last case I remember happened in 2015.

Should I install PostgreSQL minor upgrades?

Yes, you should always install minor releases as soon as they come out. The PostgreSQL versioning policy is quite outspoken on this point (the emphasis in the quote is in the original!):

While upgrading will always contain some level of risk, PostgreSQL minor releases fix only frequently-encountered bugs, security issues, and data corruption problems to reduce the risk associated with upgrading. For minor releases, the community considers not upgrading to be riskier than upgrading.

There is little to add to that statement. One thing that I want to add is that you should not test your application when you install a minor upgrade. It is enough to test the installation procedure on your test systems before you apply it to your production systems. Since testing an application is a lot of work, people who insist on testing the application with every new minor release usually end up not updating PostgreSQL. If you trust PostgreSQL, perform minor releases without testing the application. If you don't trust PostgreSQL, use a different database management system.

How do I know when there is a new minor upgrade available?

There is a PostgreSQL release roadmap that will tell you when exactly the next minor upgrades will be available. That way, you can plan minor upgrades in advance.

Occasionally, there will be an unplanned PostgreSQL minor release. That happens if somebody discovers a severe bug that affects security or causes data corruption, and the release management team decides that it would be too dangerous to wait for the next regular minor upgrade. To get alerted when that happens, you should subscribe to the “pgsql-announce” mailing list.

Is there anything to do besides installing the software and a restart?

Occasionally there will be bugs in the definition of system objects, or there could be a data corruption bug that might affect you. Installing the minor upgrade won't fix problems like these. To learn about such occurrences, you should always look at the release notes for the minor release and look at the section “Migration to version X.Y”. There is always a paragraph starting with “however”. For example, the release notes for 16.1 contain:

However, several mistakes have been discovered that could lead to certain types of indexes yielding wrong search results or being unnecessarily inefficient. It is advisable to REINDEX potentially-affected indexes after installing this update. See the first through fourth changelog entries below.

Read the referenced change log entries, and if you think you are affected by that problem, follow the instructions to fix it.

I cannot install the minor upgrade, because my software vendor does not support it!

Occasionally I hear complaints like, “I cannot upgrade to 15.5, because my application vendor only supports 15.3”. You don't want to lose support with your application vendor, but you also want to be as safe from data corruption and security problems as possible. The reason for such a requirement is always the same: the software vendor has set up a test system with PostgreSQL 15.3 and tested the application there. They don't want to upgrade, and they don't know that PostgreSQL minor updates don't change the behavior of the database. Here is what I'd suggest you should do:

• Talk to the software vendor. Point them to this article or the referenced information on the PostgreSQL web site. Make them aware that customer happiness is low if the customer suffers from data corruption in the database. Tell them that your security department has a problem with running software that has known security vulnerabilities. Tell them minor upgrades don't affect how PostgreSQL behaves, and that they can install the latest minor upgrade on their test system. A good software vendor will listen.
• If the software vendor does not care, they either don't understand a lot about the software they are working with, or they don't care about you as a customer. Try to get rid of that application.

Conclusion

Always run the latest minor release for your PostgreSQL version. Minor upgrades are simple, and they won't cause problems for you.

If you want to read more about upgrading PostgreSQL, look at this article about pg_upgrade or upgrading PostGIS and PostgreSQL.