Repository navigation
PostgreSQL 13 to 17 Upgrade Plan
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).
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.
Use a blue/green-style database cutover:
- Create a new PostgreSQL 17 deployment with a fresh PVC.
- Take a backup from the current PostgreSQL 13 deployment.
- Restore the backup into the new PostgreSQL 17 instance.
- Validate connectivity, schema, extensions, and application behavior.
- Switch the application to the new database instance.
- Keep the old deployment and PVC available for rollback until the new deployment is confirmed healthy.
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.
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.
- 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_dumpallor an equivalent backup workflow. - Note any extensions, custom roles, or special configuration used by the current 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.
- 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.
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.
- 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.
- 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.
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.
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.
- 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
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.
Before running the script, make sure you have:
-
ocinstalled and available in yourPATH - An authenticated OpenShift session (
oc logincompleted successfully) - Access to the target namespace and the database deployment
-
pg_dumpallavailable inside the PostgreSQL pod (the script uses it during backup) -
psqlavailable inside the PostgreSQL pod (the script uses it during restore) -
base64available on the local machine (used to decode the values from OpenShift secrets) - A local shell environment that can run Bash
This wiki documents NR Waste Plus for users and developers. Verify security and deployment guidance against the current application configuration before applying it elsewhere.
- Report an issue or ask a question in the GitHub repository.
- Follow the Contributing Guidelines to propose an update.
- Read the Code of Conduct.
Collection indexes support human browsing and machine retrieval. Keep both current when adding or moving wiki pages.
NR Waste Plus Wiki | GitHub Repository