Enterprise Server: Upgrading to new releases

Upgrade process

The general upgrade process for pganalyze Enterprise Server is as follows:

1. Backup the statistics database (pg_dump or RDS snapshot)

We recommend you make a backup of the pganalyze statistics database, to be able to roll back an upgrade easily (see Recovering from a failed upgrade). You don't need to save any other state besides the statistics database, and you can use a simple pg_dump for backing up the database, or any other method that allows a convenient restore (e.g. Amazon RDS snapshots).

2. Pull the new pganalyze image

docker pull quay.io/pganalyze/enterprise:[new version]

Be sure to replace [new version] with the specific release you are upgrading to. You can see the latest release on the Releases page.

3. Stop the currently running container

docker stop --rm pganalyze

4. Run rake db:migrate task in a new container

Before starting the database migration task, make sure that the btree_gist and pgcrypto extensions are installed and available.

docker run --env-file /etc/pganalyze.env quay.io/pganalyze/enterprise:[new version]   rake db:migrate

This will upgrade the database schema for the new release - at this point you need to use the new version, and can't go back to the old version without recovering from backup (as schemas are not compatible across versions).

5. Run enterprise self check

docker run --env-file /etc/pganalyze.env quay.io/pganalyze/enterprise:[new version]   rake enterprise:self_check

If this returns any errors, please review your environment configuration in pganalyze.env.

Also see Special Notes: Upgrading from earlier releases to 2018.08 and newer if you are running into a license error.

6. Start container

docker run -d --name pganalyze -p 8080:5000 --env-file /etc/pganalyze.env   quay.io/pganalyze/enterprise:[new version]

At this point you are done and the user interface should load again as expected. Please reach out to us if you run into any issues.

Recovering from a failed upgrade

In order to recover from a failed upgrade attempt, you need to first stop the pganalyze container using docker stop --rm pganalyze.

Then you would perform a regular database restore operation - on Amazon RDS you might choose to recover from a snapshot, on other systems you would usually use pg_restore from a pg_dump you have done before.

After the backup is restored, start up the container with the old version like this:

docker run -d --name pganalyze -p 8080:5000 --env-file /etc/pganalyze.env   quay.io/pganalyze/enterprise:[old version]

Special Note: Upgrading from earlier release to 2026.01 and newer

The 2026.01 release introduced the new "pco" storage format, with the migration to the format happening during the release upgrade process by default.

For large installations (100+ servers monitored), this migration may take 1 hour or longer to complete, during which time your pganalyze install would be unavailable. To keep the system online and accepting data, you can optionally delay the data backfill step to run it after migrations have been applied:

1. During the release upgrade run the migrations with SKIP_PCO_BACKFILL=1 environment variable set.
2. After the new code is deployed run these commands in a console (console command to the container / Docker entrypoint).

Rust::Migrate.migrate('20250902174735_backfill_query_stats_pco')
require './db/migrate/20251030164200_drop_query_stats_packed'
DropQueryStatsPacked.new.up
 
Rust::Migrate.migrate('20251031193250_backfill_table_stats_pco')
require './db/migrate/20251212175907_drop_table_stats_packed'
DropTableStatsPacked.new.up

Until the migration is completed the pganalyze UI will only show new data. After the migration is complete the full history will be available again.

Special Note: Upgrading from earlier releases to 2018.08 and newer

Starting in pganalyze Enterprise 2018.08.0, the pganalyze container requires the LICENSE_KEY environment variable to be configured.

Before starting the new container, set the LICENSE_KEY environment variable to the download password that you have been given when first setting up pganalyze Enterprise Server.

Note that this requires the container to be able to make an HTTPS connection (port 443) to enterprise-license-check.pganalyze.com - if this is not possible in your setup please contact support for workarounds.

After setting the LICENSE_KEY you can verify using rake enterprise:self_check that the license verification works as expected.