Minor version upgrade of Percona Distribution for PostgreSQL¶

A minor version upgrade is the upgrade within the same major version. For example, from 17.5.2 to 17.6.1.

Considerations¶

Upgrading a PostgreSQL cluster may result in downtime, as well as in failover caused by updating the primary instance.
Starting with the Operator 2.6.0, PostgreSQL images are based on Red Hat Universal Base Image (UBI) 9 instead of UBI 8. UBI 9 has a different version of collation library glibc and this introduces a collation mismatch in PostgreSQL. Collation defines how text is sorted and compared based on language-specific rules such as case sensitivity, character order and the like. PostgreSQL stores the collation version used at database creation. When the collation version changes, this may result in corruption of database objects that use it like text-based indexes. Therefore, you need to identify and reindex objects affected by the collation mismatch.

Before you start¶

We recommend to update PMM Server before upgrading PMM Client.
If you are using PMM server version 2, use a PMM client image compatible with PMM 2. If you are using PMM server version 3, use a PMM client image compatible with PMM 3.
PMM2 has reached its end-of-life stage and is deprecated in the Operator. We recommend you to migrate to and use PMM3. See PMM upgrade documentation for how to migrate from version 2 to version 3.

Upgrade steps¶

To make a minor upgrade of Percona Distribution for PostgreSQL, do the following:

Check the version of the Operator you have in your Kubernetes environment. If you need to update it, refer to the Operator upgrade guide
Check the current version of the Custom Resource and what versions of the database and cluster components are compatible with it. Replace the Operator version with your value in the following command:
```
curl https://check.percona.com/versions/v1/pg-operator/2.9.0 |jq -r '.versions[].matrix'
```
You can also find this information in the Versions compatibility matrix.
Update the database, the backup and PMM Client image names with a newer version tag. Find the image names in the list of certified images.

We recommend to update the PMM Server before the upgrade of PMM Client. If you haven’t done it yet, exclude PMM Client from the list of images to update.

Since this is a working cluster, the way to update the Custom Resource is to apply a patch with the kubectl patch pg command.

This example command updates the cluster with the name cluster1 in the namespace postgres-operator to the 2.9.0 version:
With PMM ClientWithout PMM Clientwith PostGIS
kubectl -n postgres-operator patch pg cluster1 --type=merge --patch '{ "spec": { "crVersion":"2.9.0", "image": "docker.io/percona/percona-distribution-postgresql:17.9-1", "proxy": { "pgBouncer": { "image": "docker.io/percona/percona-pgbouncer:1.25.1-1" } }, "backups": { "pgbackrest": { "image": "docker.io/percona/percona-pgbackrest:2.58.0-1" } }, "pmm": { "image": "docker.io/percona/pmm-client:3.6.0" } }}'
The following image names in the above example were taken from the list of certified images:
- docker.io/percona/percona-distribution-postgresql:17.9-1,
- docker.io/percona/percona-pgbouncer:1.25.1-1,
- docker.io/percona/percona-pgbackrest:2.58.0-1,
- docker.io/percona/pmm-client:3.6.0.
kubectl patch pg cluster1 -n postgres-operator --type=merge --patch '{ "spec": { "crVersion":"2.9.0", "image": "docker.io/percona/percona-distribution-postgresql:17.9-1", "proxy": { "pgBouncer": { "image": "docker.io/percona/percona-pgbouncer:1.25.1-1" } }, "backups": { "pgbackrest": { "image": "docker.io/percona/percona-pgbackrest:2.58.0-1" } } }}'
The following image names in the above example were taken from the list of certified images:
- docker.io/percona/percona-distribution-postgresql:17.9-1,
- docker.io/percona/percona-pgbouncer:1.25.1-1,
- docker.io/percona/percona-pgbackrest:2.58.0-1
When using the PostGIS extension, make sure to specify the image that contains it for the kubectl patch command. Add PMM client image to the list if you also use it.
kubectl patch pg cluster1 -n postgres-operator --type=merge --patch '{ "spec": { "crVersion":"2.9.0", "image": "docker.io/percona/percona-distribution-postgresql-with-postgis:17.9-1", "proxy": { "pgBouncer": { "image": "docker.io/percona/percona-pgbouncer:1.25.1-1" } }, "backups": { "pgbackrest": { "image": "docker.io/percona/percona-pgbackrest:2.58.0-1" } } }}'
The following image names in the above example were taken from the list of certified images:
- docker.io/percona/percona-distribution-postgresql-with-postgis:17.9-1,
- docker.io/percona/percona-pgbouncer:1.25.1-1,
- docker.io/percona/percona-pgbackrest:2.58.0-1

After you applied the patch, the deployment rollout will be triggered automatically. The update process is successfully finished when all Pods have been restarted.

Expected output

NAME                                           READY   STATUS      RESTARTS   AGE
cluster1-backup-4vwt-p5d9j                     0/1     Completed   0          97m
cluster1-instance1-b5mr-0                      4/4     Running     0          99m
cluster1-instance1-b8p7-0                      4/4     Running     0          99m
cluster1-instance1-w7q2-0                      4/4     Running     0          99m
cluster1-pgbouncer-79bbf55c45-62xlk            2/2     Running     0          99m
cluster1-pgbouncer-79bbf55c45-9g4cb            2/2     Running     0          99m
cluster1-pgbouncer-79bbf55c45-9nrmd            2/2     Running     0          99m
cluster1-repo-host-0                           2/2     Running     0          99m
percona-postgresql-operator-79cd8586f5-2qzcs   1/1     Running     0          120m

Scan for indexes that rely on collations other than C or POSIX and whose collations were provided by the operating system (c) or dynamic libraries (d). Connect to PostgreSQL with the privileges of the superuser or the database owner and run the following query:

SELECT DISTINCT
    indrelid::regclass::text,
    indexrelid::regclass::text,
    collname,
    pg_get_indexdef(indexrelid)
FROM (
    SELECT
        indexrelid,
        indrelid,
        indcollation[i] coll
    FROM
        pg_index,
        generate_subscripts(indcollation, 1) g(i)
) s
JOIN pg_collation c ON coll = c.oid
WHERE
    collprovider IN ('d', 'c')
    AND collname NOT IN ('C', 'POSIX');

If you see the list of affected indexes, find the database names where indexes use a different collation version:

SELECT * FROM pg_database;

Sample output

oid  |  datname  | datdba | encoding | datlocprovider | datistemplate | datallowconn | datconnlimit | datfrozenxid | datminmxid | dattablespace | datcollate  |  datctype   | daticulocale | daticurules | datcollversion |                           datacl

-------+-----------+--------+----------+----------------+---------------+--------------+--------------+--------------+------------+---------------+-------------+-------------+--------------+-------------+----------------+------------------------------------------------------------

 5 | postgres  |     10 |        6 | c              | f             | t            |
   -1 |          722 |          1 |          1663 | en_US.utf-8 | en_US.utf-8 |
 |             | 2.28           |
 1 | template1 |     10 |        6 | c              | t             | t            |
   -1 |          722 |          1 |          1663 | en_US.utf-8 | en_US.utf-8 |
 |             | 2.28           | {=c/postgres,postgres=CTc/postgres}
 4 | template0 |     10 |        6 | c              | t             | f            |
   -1 |          722 |          1 |          1663 | en_US.utf-8 | en_US.utf-8 |
 |             |                | {=c/postgres,postgres=CTc/postgres}
 16466 | cluster1  |     10 |        6 | c              | f             | t            |
   -1 |          722 |          1 |          1663 | en_US.utf-8 | en_US.utf-8 |
 |             | 2.28           | {=Tc/postgres,postgres=CTc/postgres,cluster1=CTc/postgres}
(4 rows)

Refresh collation metadata and rebuild affected indexes. This command requires the privileges of a superuser or a database owner:
```
ALTER DATABASE cluster1 REFRESH COLLATION VERSION;
```

Last update: April 1, 2026
Created: November 13, 2025