Upgrade PostgreSQL minor versions and major releases

PGO supports two distinct upgrade paths: minor version updates and major version upgrades. Minor updates swap the container image and trigger a rolling restart, keeping the cluster online throughout. Major upgrades require the PGUpgrade custom resource, which runs pg_upgrade to migrate data from one major version to the next.

Minor version updates

PostgreSQL releases minor versions frequently to deliver bug fixes and security patches. To apply a minor update, change the image field in your PostgresCluster spec to reference the newer image tag.

spec:
  postgresVersion: 16
  image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-16.3-0

Apply the change:

kubectl apply -f postgres-cluster.yaml

PGO detects the image change and performs a rolling restart of the instance pods. The primary is restarted last, so the cluster remains available throughout the update as long as you have at least one replica.

Using the RELATED_IMAGE_POSTGRES environment variable

When image is omitted from the spec, the operator uses an environment variable to look up the image. For a standard PostgreSQL 16 cluster, it reads RELATED_IMAGE_POSTGRES_16. You can update the image by changing this variable in the operator deployment instead of modifying individual cluster specs.

If you use a PostGIS-enabled image, the environment variable follows the pattern RELATED_IMAGE_POSTGRES_{version}_GIS_{postGISVersion}, for example RELATED_IMAGE_POSTGRES_16_GIS_3.4.

Major version upgrades

A major PostgreSQL upgrade—for example, from PostgreSQL 15 to 16—requires migrating the on-disk data format. PGO uses the PGUpgrade custom resource to orchestrate this process via the pg_upgrade tool.

The cluster must be shut down before running a major upgrade. The PGUpgrade resource does not perform a live upgrade. Plan for a maintenance window.

Step-by-step major upgrade

Shut down the PostgresCluster

Set spec.shutdown: true on your cluster to stop all workloads. Volumes and Services remain in place.

spec:
  shutdown: true

Confirm all pods have terminated:

kubectl get pods -l postgres-operator.crunchydata.com/cluster=hippo

Create the PGUpgrade resource

Create a PGUpgrade manifest that references your cluster by name and specifies the source and target versions.

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PGUpgrade
metadata:
  name: hippo-upgrade
spec:
  postgresClusterName: hippo
  fromPostgresVersion: 15
  toPostgresVersion: 16

Apply it:

kubectl apply -f pgupgrade.yaml

PGO creates a pod that runs pg_upgrade against the cluster’s data directory.

Monitor upgrade progress

Watch the PGUpgrade status conditions to track progress:

kubectl get pgupgrade hippo-upgrade -o jsonpath='{.status.conditions}' | jq .

The upgrade is complete when the Succeeded condition is true.

Update the PostgresCluster spec

After the upgrade job completes, update your cluster spec to reflect the new major version and the corresponding image. Set shutdown: false to restart the cluster.

spec:
  postgresVersion: 16
  image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-16.3-0
  shutdown: false

Apply the change:

kubectl apply -f postgres-cluster.yaml

Verify the upgraded cluster

Confirm PostgreSQL is running on the new version:

kubectl exec -it \
  $(kubectl get pod -l postgres-operator.crunchydata.com/cluster=hippo,postgres-operator.crunchydata.com/role=master -o name) \
  -c database -- psql -c "SELECT version();"

PGUpgrade spec reference

The full PGUpgradeSpec fields are:

Field	Type	Required	Description
`postgresClusterName`	string	Yes	Name of the `PostgresCluster` to upgrade.
`fromPostgresVersion`	integer	Yes	Source major version (e.g. `15`). Valid range: 11–18.
`toPostgresVersion`	integer	Yes	Target major version (e.g. `16`). Must be greater than `fromPostgresVersion`. Valid range: 11–18.
`image`	string	No	Image to use for the upgrade job. Defaults to the operator’s configured upgrade image.
`imagePullPolicy`	string	No	One of `Always`, `Never`, or `IfNotPresent`.
`imagePullSecrets`	[]LocalObjectReference	No	Pull secrets for the upgrade image. Changing this restarts all running `PGUpgrade` pods.
`resources`	ResourceRequirements	No	CPU and memory for the upgrade pod.
`affinity`	Affinity	No	Scheduling affinity for the upgrade pod.
`tolerations`	[]Toleration	No	Tolerations for the upgrade pod.
`priorityClassName`	string	No	Priority class for the upgrade pod. Changing this restarts the pod.
`jobs`	integer	No	Number of simultaneous `pg_upgrade` worker processes.
`transferMethod`	string	No	File transfer method: `Clone`, `Copy`, `CopyFileRange`, or `Link`. `Clone` and `CopyFileRange` require PostgreSQL 12+ and 17+ respectively.
`metadata`	Metadata	No	Labels and annotations to add to PGUpgrade resources.

PGUpgradeCPUConcurrency is a beta feature gate (enabled by default) that automatically adjusts the jobs parallelism based on available CPU resources on the upgrade pod. See Feature Gates.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Upgrade PostgreSQL minor versions and major releases

Minor version updates

Using the RELATED_IMAGE_POSTGRES environment variable

Major version upgrades

Step-by-step major upgrade

PGUpgrade spec reference

Next steps

Resize cluster resources

PGUpgrade reference

​Minor version updates

​Using the RELATED_IMAGE_POSTGRES environment variable

​Major version upgrades

​Step-by-step major upgrade

​PGUpgrade spec reference

​Next steps

Resize cluster resources

PGUpgrade reference

Minor version updates

Using the RELATED_IMAGE_POSTGRES environment variable

Major version upgrades

Step-by-step major upgrade

PGUpgrade spec reference

Next steps