1. Documentation
2. 2026.0 (Latest) 2025.1 2025.0 2024.1 2024.0 10.3 10.2 10.1 10.0 9.10 9.9 9.8 9.7 9.6 9.5 9.4 9.3 9.2 9.1 9.0 8.2 8.1 8.0 7.6
3. Hub
4. Releases
5. PostgreSQL Upgrade Guide (14 → 17)

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:

kubectl scale deployment.apps/aihub-backend-dep --replicas=0 -n <namespace>
kubectl scale deployment.apps/jupyterhub-dep --replicas=0 -n <namespace> 
kubectl scale deployment.apps/keycloak-dep --replicas=0 -n <namespace>

2. Create backups from Postgresql 14 database pods

POSTGRES_USER and POSTGRES_DB are variables set in the running container

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

Create dump inside db pod:

kubectl exec -it <postgres14-pod> -n <namespace> -- bash
  pg_dump -U "${POSTGRES_USER}" -Fc -d "${POSTGRES_DB}" -f /tmp/db14.dump
  exit

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

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

kubectl cp <namespace>/<postgres14-pod>:/tmp/db14.dump ./<component>-db14.dump

4. Scale down database deployments

kubectl scale deployment.apps/aihub-db-dep --replicas=0 -n <namespace>
kubectl scale deployment.apps/jupyterhub-db-dep --replicas=0 -n <namespace> 
kubectl scale deployment.apps/keycloak-db-dep --replicas=0 -n <namespace>

5. Delete the database PVCs

kubectl delete pvc aihub-db-pvc -n <namespace>
kubectl delete pvc jupyterhub-db-pvc -n <namespace>
kubectl delete pvc keycloak-db-pvc -n <namespace>

6. Deploy the new 2026.0.0 version of AI Hub containing Postgresql 17

Follow the usual procedure, before restoring the database in the following steps.

7. Scale down application deployments

kubectl scale deployment.apps/aihub-backend-dep --replicas=0 -n <namespace>
kubectl scale deployment.apps/jupyterhub-dep --replicas=0 -n <namespace> 
kubectl scale deployment.apps/keycloak-dep --replicas=0 -n <namespace>

8. Copy db dumps into the postgres pods and restore the database

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

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

kubectl cp ./db14.dump <namespace>/<postgres17-pod>:/tmp/db14.dump

kubectl exec -it <postgres17-pod> -n <namespace> -- bash
  pg_restore -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" -cve --if-exists /tmp/db14.dump && if [[ "$?" == "0" ]];then echo "Restore completed successfully"; else echo "Restore failed"; fi
  exit

9. Scale applications up

kubectl scale deployment.apps/aihub-backend-dep --replicas=1 -n <namespace>
kubectl scale deployment.apps/jupyterhub-dep --replicas=1 -n <namespace> 
kubectl scale deployment.apps/keycloak-dep --replicas=1 -n <namespace>

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