AIR PostgreSQL 15 → 18 Upgrade Guide

This guide walks you through upgrading the PostgreSQL database in a self-hosted AIR deployment from PostgreSQL 15 to PostgreSQL 18. It covers single-tier, two-tier, and offline (air-gapped) deployments.

1. One Day Before

Complete the following preparation steps at least 24 hours before your planned PostgreSQL upgrade.

Recommended actions the day before:

Before the maintenance window opens, ask your team to close any cases that are no longer actively being worked on.

This is strongly recommended. During the upgrade, the AIR database will be unavailable for a period of time. Closing idle cases in advance has two benefits: it protects against data loss for any unsaved work, and it allows AIR’s internal database operations to complete — freeing up the disk space that those cases were occupying. Make sure AIR has been running normally for at least one full day after the case closures so that these cleanup operations have time to finish and the freed disk space is properly reflected before you check disk requirements.
Notify all AIR users of the upcoming maintenance window and its expected duration.
Ask users to close any cases they are no longer actively using.
Confirm with team leads that no time-sensitive case activity is expected during the window.

2. Before the Upgrade

We strongly recommend taking an AIR Backup before starting the upgrade.

During the PostgreSQL upgrade, the database is offline. While the upgrade is in progress:

Users cannot log in to AIR.
Database operations are not available.
API requests requiring database access may fail.
Background jobs that require the database resume after the upgrade completes.

Although the upgrade process preserves your data, an AIR Backup provides an additional recovery option in the unlikely event of an unexpected failure.

What is an AIR Backup?

An AIR Backup is a pg_dump-based export of your AIR data, taken through the AIR application. It captures the logical contents of your database and can be used to restore your data into a working AIR environment. See Backup.

AIR Backup vs. `--keep-legacy-backup`

These are two distinct mechanisms that serve different purposes:

	AIR Backup	`--keep-legacy-backup`
What it is	A `pg_dump` export of AIR data	A raw copy of the entire PostgreSQL 15 cluster directory
Who manages it	You, before the upgrade	The upgrade script, automatically
Used for	Data recovery, migration, general restore	Rollback to PostgreSQL 15 if the upgrade fails
Data coverage	Point-in-time snapshot of AIR application data	Full cluster state at the moment of upgrade

Both are recommended. Take an AIR Backup yourself before starting, and run the upgrade with --keep-legacy-backup to preserve the rollback option.

Disk space requirement

Before starting the upgrade, confirm that the host has enough free disk space. The upgrade process copies the entire PostgreSQL cluster before swapping to the new version, so it needs room for both copies to exist simultaneously.

Minimum free disk space required: 1.2× the current PostgreSQL cluster size.

You don’t have to calculate this manually. The pg-upgrade.sh script can verify it for you with the --disk-space-check flag. This is a read-only check — it does not change any configuration, restart the database, or start the upgrade.

Step 1 — Download the upgrade script

cd /opt/binalyze-air
curl -fsSL https://cdn.binalyze.com/air-deploy/pg-upgrade.sh -o pg-upgrade.sh
chmod +x pg-upgrade.sh

Step 2 — Run the disk space check

sudo -E bash pg-upgrade.sh --disk-space-check

The check reports:

the current PostgreSQL cluster size,
the free space required for the upgrade (1.2× the cluster size),
the space currently available on the data volume, and
a clear PASS / FAIL result.

If you plan to keep the rollback backup (--keep-legacy-backup), the report also shows the extra space the retained PostgreSQL 15 backup will occupy — long-term usage stays at roughly 2× the cluster size while the backup is kept.

If the check fails, free up disk space (for example, close idle cases as described above and let AIR run for a day so cleanup completes), then run it again before starting the upgrade.

Run the check on the DB host, using that host’s AIR folder:

cd /opt/binalyze-air-db
curl -fsSL https://cdn.binalyze.com/air-deploy/pg-upgrade.sh -o pg-upgrade.sh
chmod +x pg-upgrade.sh
sudo AIR_FOLDER=/opt/binalyze-air-db bash pg-upgrade.sh --disk-space-check

3. Running the PostgreSQL Upgrade

The upgrade is performed by the pg-upgrade.sh script. It sets the required flags, restarts the database service, streams progress logs, and manages the old PostgreSQL 15 data.

About `--keep-legacy-backup`

The upgrade script accepts an optional flag: --keep-legacy-backup

We recommend using this flag.

Without `--keep-legacy-backup`	With `--keep-legacy-backup`
The PostgreSQL 15 backup is deleted automatically after a successful upgrade.	The PostgreSQL 15 backup (`postgresql.pg15.bak/`) is preserved on disk.
Rollback is not possible after the upgrade completes.	Rollback remains possible for as long as the backup exists.
Disk space is reclaimed immediately.	Disk space is reclaimed later, when you finalize (see Finalizing: Removing the Legacy Backup).

Using --keep-legacy-backup gives you a rollback window after the upgrade. You decide when to finalize and remove the old backup once you are confident the upgrade is stable.

3.1 Single-Tier Deployments

Run all commands on the single AIR host.

Step 1 — Download the upgrade script

cd /opt/binalyze-air
curl -fsSL https://cdn.binalyze.com/air-deploy/pg-upgrade.sh -o pg-upgrade.sh
chmod +x pg-upgrade.sh

Step 2 — Run the upgrade with backup

sudo -E bash pg-upgrade.sh --keep-legacy-backup

Large databases may spend several minutes in checksum verification. This is normal — wait for the process to complete.

3.2 Two-Tier Deployments

Run all commands on the DB host only. The console/app host is not involved in the PostgreSQL upgrade.

Step 1 — Stop app containers

cd /opt/binalyze-air
docker compose down

Step 2 — Download the upgrade script

cd /opt/binalyze-air-db
curl -fsSL https://cdn.binalyze.com/air-deploy/pg-upgrade.sh -o pg-upgrade.sh
chmod +x pg-upgrade.sh

Step 3 — Run the upgrade with backup

sudo AIR_FOLDER=/opt/binalyze-air-db bash pg-upgrade.sh --keep-legacy-backup

3.3 Offline Deployments

For offline environments, pg-upgrade.sh is not included in the offline bundle and must be obtained separately. Download it from a machine with internet access and manually copy it to the correct path on the target host before starting:

Single-tier: copy to /opt/binalyze-air/pg-upgrade.sh
Two-tier DB host: copy to /opt/binalyze-air-db/pg-upgrade.sh

Offline Single-Tier

Step 1 — Run the upgrade with backup

cd /opt/binalyze-air
chmod +x pg-upgrade.sh
sudo -E bash pg-upgrade.sh --keep-legacy-backup

Offline Two-Tier

Step 1 — Stop app containers

Run on the DB host only.

cd /opt/binalyze-air
docker compose down

Step 2 — Copy and make the upgrade script executable

Copy pg-upgrade.sh to /opt/binalyze-air-db/, then:

cd /opt/binalyze-air-db
chmod +x pg-upgrade.sh

Step 3 — Run the upgrade with backup

sudo AIR_FOLDER=/opt/binalyze-air-db bash pg-upgrade.sh --keep-legacy-backup

Monitoring the Upgrade

Use the same AIR_FOLDER value used for the upgrade.

Single-tier:

export AIR_FOLDER=/opt/binalyze-air
sudo -E bash pg-upgrade.sh --get-status
sudo -E bash pg-upgrade.sh --get-logs

Two-tier DB host:

export AIR_FOLDER=/opt/binalyze-air-db
sudo -E bash pg-upgrade.sh --get-status
sudo -E bash pg-upgrade.sh --get-logs

Post-Upgrade Verification

Before closing the maintenance window, confirm the upgrade completed successfully.

Check that containers are healthy:

# Single-tier
docker compose --project-directory /opt/binalyze-air ps

# Two-tier DB host
docker compose --project-directory /opt/binalyze-air-db ps

Confirm the PostgreSQL version is 18:

# Single-tier
docker compose --project-directory /opt/binalyze-air exec data-master \
  psql -U air-data -d airdb -c "SHOW server_version;"

# Two-tier DB host
docker compose --project-directory /opt/binalyze-air-db exec data-master \
  psql -U air-data -d airdb -c "SHOW server_version;"

Validate the application:

Log in to AIR and confirm the main pages load.
Verify that existing case data is visible.
Confirm background jobs and services are running normally.

4. Rolling Back

Single-tier:

cd /opt/binalyze-air
export AIR_FOLDER=/opt/binalyze-air
sudo -E bash pg-upgrade.sh --rollback

Two-tier DB host:

cd /opt/binalyze-air-db
export AIR_FOLDER=/opt/binalyze-air-db
sudo -E bash pg-upgrade.sh --rollback

The rollback process stops data-master, restores the PostgreSQL 15 cluster from the backup directory, and restarts the service.

If your console/app tier was also updated to a release that requires PostgreSQL 18, you also need to roll it back to the previous compatible AIR release.

5. Troubleshooting: Sending Logs to Support

If the upgrade fails or data-master enters a crash loop, collect a diagnostic archive before contacting Support.

Archive logs — Single-tier:

export AIR_FOLDER=/opt/binalyze-air
sudo -E bash pg-upgrade.sh --archive-logs

Archive logs — Two-tier DB host:

export AIR_FOLDER=/opt/binalyze-air-db
sudo -E bash pg-upgrade.sh --archive-logs

The archive is saved under:

<AIR_FOLDER>/pg-upgrade-logs-<UTC>.zip

When contacting Binalyze Support at [email protected], include:

Your deployment topology (single-tier / two-tier / offline)
AIR version before the upgrade
Target AIR version
The value of AIR_FOLDER
Whether --keep-legacy-backup was used
The archived log ZIP file

6. Finalizing: Removing the Legacy Backup

If you ran the upgrade with --keep-legacy-backup, the PostgreSQL 15 backup (postgresql.pg15.bak/) is kept on disk until you explicitly remove it. This is intentional — it preserves your rollback option.

Once you are satisfied that the upgrade is stable and you no longer need the rollback option, you can reclaim the disk space using the --reclaim-legacy-disk flag.