CNPG upgrades at a glance

PostgreSQL's annual major releases bring performance work, new features and compatibility changes, but they can also change the internal storage format. Minor releases within a major version are backward-compatible, while major jumps need careful handling. CloudNativePG (CNPG) offered only limited upgrade capabilities before version 1.26, which added offline in-place upgrades to the existing options of logical dump/restore and logical replication. From v1.26 onward, a major upgrade becomes a declarative, Kubernetes-native operation.

Minor version upgrades

Minor releases carry bug and security fixes and remain compatible across the same major version. CNPG handles them as a rolling upgrade: replicas are upgraded first, then the primary, either through a switchover to a replica or a restart of the primary.

Rolling a cluster from 16.0 to 16.10

Starting from a cluster on PostgreSQL 16.0, the only change required is imageName in the cluster manifest.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: minor-upgrade
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.0
  storage:
    size: 1Gi

Applying the manifest and checking the cluster confirms the new version and status.

kubectl cnpg status minor-upgrade

System ID: 7556540389940686868
PostgreSQL Image: ghcr.io/cloudnative-pg/postgresql:16.0
Primary instance: minor-upgrade-1
Primary start time: 2025-10-02 08:36:08 +0000 UTC (uptime 5m37s)
Status: Cluster in healthy state
Instances: 3
Ready instances: 3

The upgrade to 16.10 changes the binary image only, so the primary is restarted and the system ID stays the same.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: minor-upgrade
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.10
  storage:
    size: 1Gi

Major version upgrades

A major upgrade starts from a running cluster on 16.10 and declares the new version in the Cluster spec. In this walkthrough the target is PostgreSQL 18.0, and the pagila sample database is imported beforehand for verification.

kubectl apply -f cluster-minor-upgrade.yaml

Applying the updated manifest triggers an offline in-place upgrade. CNPG first records the current version and image under .status.pgDataImageInfo so the previous state is recoverable, then runs an upgrade job that:

  • shuts down all cluster pods using smart mode;
  • creates new directories for PGDATA and, where applicable, for WAL files and tablespaces;
  • verifies that the image binaries and data files match a major upgrade request via pg_upgrade --check;
  • performs the upgrade with pg_upgrade --link;
  • replaces the original directories with the upgraded ones on success.
kubectl cnpg status minor-upgrade

System ID: 7556540389940686868
PostgreSQL Image:    ghcr.io/cloudnative-pg/postgresql:16.10
Primary instance:    minor-upgrade-1
Primary start time:  2025-10-02 08:36:08 +0000 UTC (uptime 1h14m8s)
Status:              Cluster in healthy state 
Instances:           3
Ready instances:     3

The replica nodes are replaced rather than reused. Once the upgrade succeeds, CNPG initializes new replicas, and high availability stays unavailable until they have caught up. Querying the imported test database confirms the data is intact.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: minor-upgrade
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.10
  storage:
    size: 1Gi

Operational caveats

  • In-place upgrades require downtime, so applications must be able to tolerate it.
  • Major upgrades are supported only between images based on the same operating system distribution.
  • CNPG does not manage PostgreSQL extensions, so extension compatibility between source and target versions has to be tested.
  • On large clusters in particular, replicas may be unavailable for a while after the primary is upgraded, which leaves high availability disabled until they return. If a failure occurs during replica initialization, recovery means restoring from the latest full backup — hence the recommendation to take a full backup after the upgrade.
  • Upgrades carry inherent risk, so a full backup before starting the process is strongly recommended.

Takeaways

  • Minor upgrades need no more than an imageName update: CNPG rolls replicas and the primary with minimal disruption.
  • Major upgrades, available since CNPG v1.26, use an offline in-place process driven by pg_upgrade. Downtime is required, but the operation is repeatable and integrated into the reconciliation loop.