Skip to content

Portal 1.20.0 Upgrade Guide

Overview

Portal 1.20.0 upgrades the internal PostgreSQL database from version 10 to version 18. The upgrade runs automatically as part of the standard upgrade command:

cd portal-docker-setup/setup
./make.sh upgrade

No separate action is required. If the instance is already running PostgreSQL 18 or newer, the step is skipped (No upgrade needed).

Customers do not query the Portal's internal PostgreSQL directly, so no dashboard or datasource changes are expected from the database upgrade itself.

What happens during the upgrade

The upgrade is a logical dump/restore, executed in phases:

  1. Version check — compares the running database version with the target; exits immediately if no upgrade is needed.
  2. Validation — checks required tools and free disk space (at least 3× the current database size must be available).
  3. Backup — takes a full SQL dump (pg_dumpall) and archives the existing data directory.
  4. Switch — stops the old database container and points the stack at the new PostgreSQL image.
  5. Start — starts a fresh PostgreSQL 18 instance.
  6. Restore — loads the SQL dump into the new instance and verifies the restored databases match the pre-upgrade state.

Progress is logged step by step (Entering phase0 … phase6). A successful run ends with:

PostgreSQL upgrade completed successfully!

Expected downtime

Application services are stopped just before the backup (phase 2) so that no writes can be lost between the dump and the restore, and are started again once the restored database is verified. The Portal is therefore unavailable from phase 2 until the end of phase 6. For a typical installation this takes a few minutes; larger databases take proportionally longer (the dump and restore each scale with database size).

Backup artifacts

Two artifacts are created next to the setup directory and are intentionally kept after a successful upgrade:

Artifact Location
SQL dump portal-docker-setup/setup/portal_backup_<timestamp>.sql
Old data directory portal-docker-setup/for_mounting/pgdata_backup_<timestamp>/

Cleaning up

Keep both artifacts until you have confirmed the Portal works normally after the upgrade (log in, open dashboards, check data). After that they can be safely deleted:

cd portal-docker-setup
rm setup/portal_backup_<timestamp>.sql
sudo rm -rf for_mounting/pgdata_backup_<timestamp>

If the upgrade fails

The upgrade rolls back automatically: on any failure it restores the archived data directory, reverts the database image to the original version, and restarts the stack in its pre-upgrade state. The log will show Performing rollback to original database version... followed by cleanup messages.

Manual rollback

If the automatic rollback did not complete (for example, the host lost power mid-upgrade), restore the pre-upgrade state manually:

cd portal-docker-setup/setup

# 1. Stop the database service
docker compose -f docker-compose.yml stop db

# 2. Put the archived data directory back
sudo rm -rf ../for_mounting/pgdata
mv ../for_mounting/pgdata_backup_<timestamp> ../for_mounting/pgdata

# 3. Revert the database image: remove the IMAGE_DB override
#    from env/compose.local.env and env/compose.generated.env
#    (or set it back to the original postgres:10.x image)

# 4. Restart the stack
./make.sh up

Then collect the following and contact Zuar support before retrying:

docker compose -f docker-compose.yml logs --tail 50 db
ls -la ../for_mounting/ | grep pgdata

The SQL dump (portal_backup_<timestamp>.sql) is the safety net for the restore step — do not delete it while investigating a failed upgrade.