PGUpgrade CRD field reference for major version upgrades

The PGUpgrade custom resource drives major PostgreSQL version upgrades for clusters managed by PGO. It runs pg_upgrade in a Kubernetes Job, converting the cluster’s data files from one major PostgreSQL version to another. You create a PGUpgrade, wait for it to complete, and then resume your PostgresCluster running the new version. API group: postgres-operator.crunchydata.com/v1beta1 Kind: PGUpgrade Scope: Namespaced

Upgrade workflow

Performing a major PostgreSQL version upgrade requires coordinating the PGUpgrade resource with your PostgresCluster. Follow these steps:

Pause the PostgresCluster

Set spec.paused: true on your PostgresCluster to stop reconciliation while the upgrade runs.

kubectl patch postgrescluster hippo --type merge \
  -p '{"spec":{"paused":true}}'

Create the PGUpgrade resource

Apply a PGUpgrade manifest targeting your cluster. The fromPostgresVersion must match the cluster’s current version and toPostgresVersion must be a higher major version.

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

Wait for the upgrade Job to complete

Monitor the PGUpgrade status conditions until Succeeded becomes True.

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

Update the PostgresCluster version and resume

Update spec.postgresVersion on your PostgresCluster to the new version and clear the paused flag.

kubectl patch postgrescluster hippo --type merge \
  -p '{"spec":{"postgresVersion":16,"paused":false}}'

Delete the PGUpgrade resource

Once the cluster is running successfully on the new version, delete the PGUpgrade resource.

kubectl delete pgupgrade hippo-upgrade

Major version upgrades cannot be reversed. Take a full pgBackRest backup before starting the upgrade and verify it is accessible. See the backups guide.

Example

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PGUpgrade
metadata:
  name: hippo-upgrade
spec:
  postgresClusterName: hippo
  fromPostgresVersion: 15
  toPostgresVersion: 16
  jobs: 4
  transferMethod: Clone
  resources:
    requests:
      cpu: "1"
      memory: 1Gi
    limits:
      cpu: "2"
      memory: 2Gi

Spec fields

string

required

The name of the PostgresCluster to upgrade. The cluster must exist in the same namespace as this PGUpgrade.

postgresClusterName: hippo

integer

required

The major PostgreSQL version of the cluster before the upgrade. Must be less than toPostgresVersion. Accepted values: 11–18.

fromPostgresVersion: 15

integer

required

The major PostgreSQL version to upgrade to. Must be greater than fromPostgresVersion. Accepted values: 11–18.

toPostgresVersion: 16

integer

Number of simultaneous pg_upgrade worker processes. Higher values can speed up the upgrade on multi-core nodes. Minimum: 0 (uses pg_upgrade default).

jobs: 4

string

The method pg_upgrade uses to transfer data files to the new cluster. Available methods depend on the PostgreSQL version being upgraded to.

Value	Available since	Description
`Copy`	Always	Copies each file. Safest; slowest for large databases.
`Link`	Always	Creates hard links. Fast but modifies old data directory — requires separate backup.
`Clone`	PostgreSQL 12+	Uses copy-on-write file cloning (requires filesystem support, e.g. APFS, Btrfs, XFS).
`CopyFileRange`	PostgreSQL 17+	Uses the `copy_file_range` syscall. Efficient on supported Linux kernels.

When not specified, pg_upgrade selects its default for the target version.

string

Container image for the pg_upgrade tool. When omitted, the operator resolves the image from its environment configuration.

image: registry.developers.crunchydata.com/crunchydata/crunchy-upgrade:ubi8-16.2-0

string

Image pull policy for the upgrade container. One of: Always, Never, IfNotPresent.

[]LocalObjectReference

Image pull secrets for pulling the upgrade image from a private registry. Changing this value causes all running PGUpgrade pods to restart.

imagePullSecrets:
  - name: my-registry-secret

ResourceRequirements

Compute resource requests and limits for the pg_upgrade container.

resources:
  requests:
    cpu: "2"
    memory: 2Gi
  limits:
    cpu: "4"
    memory: 4Gi

Affinity

Kubernetes affinity rules for scheduling the upgrade pod. Useful for placing the upgrade Job on nodes with sufficient resources or specific storage access.

[]Toleration

Tolerations for scheduling the upgrade pod onto tainted nodes.

string

Priority class name for the upgrade pod. Changing this value causes the pod to restart.

Metadata

Labels and annotations to apply to the upgrade Job and pod.

metadata:
  labels:
    upgrade-version: "16"
  annotations:
    example.com/ticket: "OPS-1234"

Status fields

Field	Type	Description
`status.conditions`	`[]Condition`	Observations of the upgrade’s current state. Monitor for `type: Succeeded`.
`status.observedGeneration`	`integer`	The `.metadata.generation` on which the status was last based.

Monitor upgrade progress with:

kubectl describe pgupgrade hippo-upgrade
kubectl get pgupgrade hippo-upgrade -o jsonpath='{.status.conditions[*].message}'

Custom Resources

Configuration

Troubleshooting

PGUpgrade CRD field reference for major version upgrades

Upgrade workflow

Example

Spec fields

Status fields

​Upgrade workflow

​Example

​Spec fields

​Status fields

​Related resources

Upgrade workflow

Example

Spec fields

Status fields

Related resources