Major PostgreSQL upgrade (13 → 14) with TimescaleDB multi-node + Patroni via Helm – data directory incompatibility

TimescaleDB and PostgreSQL
1

Hi,

I’m running TimescaleDB in multi-node mode deployed via Helm 3, and I’m looking for guidance on performing a major PostgreSQL upgrade without data loss.

Current setup

  • PostgreSQL: 13.22

  • TimescaleDB: 2.5.0

  • Deployment: Kubernetes, Helm 3

  • HA: Patroni

  • Topology:

    • 2 × TimescaleDB data node pods (StatefulSet)

    • 2 × TimescaleDB coordinator pods (StatefulSet)

  • Distributed hypertables enabled

Persistent volumes

  • Data node pods

    • 1 PVC mounted at:

      /var/lib/postgresql/storage

  • Coordinator pods

    • 2 PVCs mounted at:

      /var/lib/postgresql/storage
/var/lib/postgresql/wal

Upgrade goal

  • Upgrade PostgreSQL from 13.22 → 14.20

  • Keep TimescaleDB at version 2.5.0

  • Perform the upgrade via helm upgrade

  • Use:

    • Source image: PostgreSQL 13.22 + TimescaleDB 2.5.0

    • Target image: PostgreSQL 14.20 + TimescaleDB 2.5.0

  • Reuse the existing PVCs

  • No data loss

What I tried

I performed a helm upgrade that updates the container (datanodes and coordinators) image from PostgreSQL 13.22 to PostgreSQL 14.20.

Since the PVCs are preserved across StatefulSet upgrades, the existing PostgreSQL data directory is reused.

Resulting error

On pod startup, PostgreSQL fails with:

FATAL: database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 13, which is not compatible with this version 14.20.

Additionally:

  • The PG_VERSION file in the data directory remains 13

  • No automatic upgrade of the data directory occurs

Question

What is the recommended approach to perform a major PostgreSQL upgrade (13 → 14) in a TimescaleDB multi-node + Patroni setup running on Kubernetes, while reusing PVCs and performing the upgrade via Helm?

Specifically:

  • Is pg_upgrade required, and if so, how should it be orchestrated per coordinator and data node?

  • Is an in-place major upgrade during a Helm upgrade supported?

  • Are there any documented best practices or reference architectures for this scenario?

  • Could be this done via a backup and restore?

Any guidance or examples would be greatly appreciated.

Thanks in advance!

2

Any help for this please? @Rory could you help?