PostgreSQL Upgrade Guide from PostgreSQL 14 to 17

This document explains how to upgrade PostgreSQL from version 14 (used by default in previous releases to version 17 (default starting with this release) in a docker compose deployment using pg_dump and pg_restore.

The affected components are Keycloak, AiHub Backend, and JupyterHub.

1. Scale Down Application Deployments

Before the upgrade, the backup part of the migration shall be done.

To ensure data integrity, scale down all application deployments that connect to PostgreSQL, that will avoid writes during the process:

docker compose stop aihub-backend
docker compose stop keycloak
docker compose stop jupyterhub

2. Create backups from Postgresql 14 databases

POSTGRES_USER and POSTGRES_DB are variables set in the running container

Repeat this step for each database (aihub-postgresql keycloak-db jupyterhub-db)

Create dumps inside db containers:

docker compose exec aihub-postgresql /bin/bash
  pg_dump -U "${POSTGRES_USER}" -Fc -d "${POSTGRES_DB}" -f /tmp/aihub-db14.dump
  exit

docker compose exec keycloak-db /bin/bash
  pg_dump -U "${POSTGRES_USER}" -Fc -d "${POSTGRES_DB}" -f /tmp/keycloak-db14.dump
  exit

docker compose exec jupyterhub-db /bin/bash
  pg_dump -U "${POSTGRES_USER}" -Fc -d "${POSTGRES_DB}" -f /tmp/jupyterhub-db14.dump
  exit

3. Copy the database dump files from the container to your local machine

docker compose cp aihub-postgresql:/tmp/aihub-db14.dump ./aihub-db14.dump
docker compose cp keycloak-db:/tmp/keycloak-db14.dump ./keycloak-db14.dump
docker compose cp jupyterhub-db:/tmp/jupyterhub-db14.dump ./jupyterhub-db14.dump

4. Stop all services

docker compose down

5. Delete database volumes

Please note, that the new PostgreSQL 17 deployment requires an empty volume and can not be started if there is a filesystem layout initialized for PostgreSQL 14 on the volume.

docker volume rm aihub-db-vol
docker volume rm keycloak-db-vol
docker volume rm jupyterhub-db-vol

6. Apply upgrade-related changes and start the database services

Please make sure that the 2026.0.0 Postgresql images are refered.

docker compose up -d aihub-postgresql keycloak-db jupyterhub-db

7. Copy the db dump files into the PostgreSQL containers and restore the database

After the database containers are started, please check their logs to ensure they are running as expected.

Repeat this step for each database (aihub-postgresql keycloak-db jupyterhub-db)

docker compose cp ./aihub-db14.dump aihub-postgresql:/tmp/aihub-db14.dump

docker compose exec aihub-postgresql /bin/bash
  pg_restore -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" -cve --if-exists /tmp/aihub-db14.dump && if [[ "$?" == "0" ]];then echo "Restore completed successfully"; else echo "Restore failed"; fi
  exit

docker compose cp ./keycloak-db14.dump keycloak-db:/tmp/keycloak-db14.dump

docker compose exec keycloak-db /bin/bash
  pg_restore -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" -cve --if-exists /tmp/keycloak-db14.dump && if [[ "$?" == "0" ]];then echo "Restore completed successfully"; else echo "Restore failed"; fi
  exit

docker compose cp ./jupyterhub-db14.dump jupyterhub-db:/tmp/jupyterhub-db14.dump

docker compose exec jupyterhub-db /bin/bash
  pg_restore -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" -cve --if-exists /tmp/jupyterhub-db14.dump && if [[ "$?" == "0" ]];then echo "Restore completed successfully"; else echo "Restore failed"; fi
  exit

9. Start all the services

docker-compose up -d

PostgreSQL has now been successfully upgraded from 14 to 17 and the data has been restored.

Categories

Versions