Skip to content

PostgreSQL 13 to 17 Upgrade Plan

Paulo Gomes da Cruz Junior edited this page Jul 3, 2026 · 1 revision

PostgreSQL 13 to 17 Upgrade Plan for OpenShift

This page captures a safe rollout plan for moving the Waste Plus database from PostgreSQL 13 to PostgreSQL 17 in OpenShift when the database is backed by a persistent volume claim (PVC).

Summary

A direct in-place upgrade from PostgreSQL 13 to 17 is not safe to assume for an existing PVC-backed deployment. The recommended path is to perform a staged migration using a new PostgreSQL 17 data volume, validate the migrated data, and only then switch the application over.

Recommended approach

Use a blue/green-style database cutover:

  1. Create a new PostgreSQL 17 deployment with a fresh PVC.
  2. Take a backup from the current PostgreSQL 13 deployment.
  3. Restore the backup into the new PostgreSQL 17 instance.
  4. Validate connectivity, schema, extensions, and application behavior.
  5. Switch the application to the new database instance.
  6. Keep the old deployment and PVC available for rollback until the new deployment is confirmed healthy.

When to use this plan

Use this plan when:

  • The current deployment uses a mounted PVC for PostgreSQL data.
  • The application must preserve existing production or non-production data.
  • You want to reduce risk before a major version change.

Preconditions

Before starting the migration, confirm the following:

  • The current database deployment is healthy and the application is not mid-write burst.
  • You have a recent backup of the database.
  • You know the database credentials and the secret values already used by the deployment.
  • You have a maintenance window for the database cutover.
  • You have enough storage for a second PVC during migration.

Rollout steps

1. Prepare the current deployment

  • Scale the application down or place it into maintenance mode so writes stop during the cutover.
  • Record the current PostgreSQL version and the current deployment configuration.
  • Capture the current database backup using a tool such as pg_dumpall or an equivalent backup workflow.
  • Note any extensions, custom roles, or special configuration used by the current deployment.

2. Create a staging PostgreSQL 17 deployment

  • Create a new OpenShift deployment using the PostgreSQL 17 image.
  • Mount a new PVC instead of reusing the existing one.
  • Reuse the existing database secrets and configuration where possible.
  • Keep the staging deployment isolated from the active application until validation is complete.

3. Restore the data

  • Restore the backup into the new PostgreSQL 17 deployment.
  • If the environment uses extensions or custom roles, verify that they restore correctly.
  • Check for application-specific objects such as functions, indexes, and grants.

4. Validate the new database

Validate the following before switching traffic:

  • The database starts successfully.
  • The application can connect to the database.
  • Queries that are important to the application return the expected results.
  • Any required extensions are present and working.
  • The data volume size and performance look acceptable for the expected workload.

5. Cut over

  • Update the application deployment to point to the new database service or new deployment.
  • Keep the old deployment available for rollback until the new one has been stable for a suitable period.
  • Re-enable the application and monitor logs and health checks.

6. Cleanup and follow-up

  • Once the cutover is confirmed stable, remove the old deployment and PVC only after the rollback window closes.
  • Update the deployment templates and release notes to document the PostgreSQL 17 rollout.
  • Record the successful migration steps for future maintenance runs.

Rollback plan

If the migration fails or validation is not successful:

  • Keep the old PostgreSQL 13 deployment running.
  • Revert the application configuration to use the original database service.
  • Preserve the failed staging deployment and logs for troubleshooting.
  • Do not delete the old PVC until the new deployment is proven reliable.

Non-production or disposable environments

If the environment is non-production and data loss is acceptable, the simplest option is:

  • Create a fresh PostgreSQL 17 deployment.
  • Reinitialize the database from scratch.
  • Reconfigure the application to use the new deployment.

This is the lowest-risk option for temporary environments but should not be used for production or environments with important persisted data.

Operational checklist

  • Backup captured
  • New PostgreSQL 17 deployment created
  • New PVC provisioned
  • Data restored successfully
  • Application connectivity verified
  • Cutover completed
  • Old deployment retained for rollback window
  • Old resources cleaned up after validation

Helper script

A helper script is available at postgres-13-to-17-openshift-migrate.sh. It uses the OpenShift CLI (oc) to discover the database deployment and pod in a namespace, prompt for the namespace, and run either a backup or restore phase.

Dependencies

Before running the script, make sure you have:

  • oc installed and available in your PATH
  • An authenticated OpenShift session (oc login completed successfully)
  • Access to the target namespace and the database deployment
  • pg_dumpall available inside the PostgreSQL pod (the script uses it during backup)
  • psql available inside the PostgreSQL pod (the script uses it during restore)
  • base64 available on the local machine (used to decode the values from OpenShift secrets)
  • A local shell environment that can run Bash

Waste Plus Wiki

Home

Architecture

Codes

Decisions

Knowledge Base

Development

Changes

Clone this wiki locally