Enterprise Server: Upgrade Azure AKS

These are the upgrade instructions for pganalyze Enterprise Server for a Kubernetes cluster managed by Azure AKS.

Before proceeding, review the upgrade overview for the general process and any release-specific notes that may apply to your upgrade.

Upgrade Steps

Step 1: Back up the statistics database

Before any upgrade, take a backup of your pganalyze statistics database. This is your recovery path if something goes wrong.

You can use pg_dump or an Azure Database for PostgreSQL snapshot. No other state needs to be saved — all configuration lives in your Kubernetes secret and deployment manifest.

Step 2: Pull the new image and push it to ACR

These steps are run on a machine with internet access and Docker installed. Replace [new version] with the release you are upgrading to — check the Releases page for the latest version. The format of the version string is v2026.01.0 (year, month of release, minor updates).

Log in to the pganalyze image registry:

docker login -e="." -u="pganalyze+enterprise_customer" -p="YOUR_PASSWORD" quay.io

Pull the new version:

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

Log in to your Azure Container Registry and push the new image:

az acr login --name pganalyzeregistry
 
docker tag quay.io/pganalyze/enterprise:[new version] \
  pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version]
 
docker push pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version]

Alternatively, if your ACR has outbound internet access, you can use az acr import to have Azure pull the image directly from Quay server-side — no local Docker installation or download required:

az acr import \
  --name pganalyzeregistry \
  --source quay.io/pganalyze/enterprise:[new version] \
  --image pganalyze-enterprise:[new version] \
  --username "pganalyze+enterprise_customer" \
  --password "YOUR_PASSWORD"

This is the simpler option for most environments. Use the manual pull/tag/push approach above if your ACR does not have outbound internet access, or if your organization requires images to be scanned before being pushed to a registry.

Step 3: Scale down the current deployment

Stop the currently running pganalyze pods by scaling the deployment to zero replicas. This ensures no application code is running against the database while you perform the migration:

kubectl scale deployment pganalyze --replicas=0

Confirm that all pods have stopped:

kubectl get pods -l app=pganalyze

The output should show no running pods before you proceed.

Step 4: Run the database migration

Run the following command, replacing [new version] with the version you are upgrading to:

kubectl run pganalyze-migrate --rm -i \
  --image=pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version] \
  --restart=Never \
  --overrides='{
    "spec": {
      "containers": [{
        "name": "pganalyze-migrate",
        "image": "pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version]",
        "command": ["/docker-entrypoint.enterprise.sh"],
        "args": ["rake", "db:migrate"],
        "envFrom": [{"secretRef": {"name": "pganalyze-secret"}}]
      }]
    }
  }'

This will stream output directly to your terminal. You may see the message "If you don't see a command prompt, try pressing enter" — this is expected and can be ignored. Output will appear on its own shortly after. The pod is automatically deleted when the command exits. Wait for it to return to your shell prompt before proceeding.

At this point the database schema has been upgraded to the new version. Rolling back now requires restoring from the backup taken in Step 1.

Step 5: Run the Enterprise self-check

Run the following command, again replacing [new version]:

kubectl run pganalyze-selfcheck --rm -i \
  --image=pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version] \
  --restart=Never \
  --overrides='{
    "spec": {
      "containers": [{
        "name": "pganalyze-selfcheck",
        "image": "pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version]",
        "command": ["/docker-entrypoint.enterprise.sh"],
        "args": ["rake", "enterprise:self_check"],
        "envFrom": [{"secretRef": {"name": "pganalyze-secret"}}]
      }]
    }
  }'

Output will stream directly to your terminal. Confirm the expected output before proceeding:

Testing Redis connection... Success!
Skipping SMTP mailer check - configure MAILER_URL to enable mail sending
Verifying enterprise license... Success!
All tests completed successfully!

If you see any errors, review your Kubernetes secret values. You can decode your current secret values with:

kubectl get secret pganalyze-secret \
  -o jsonpath='{.data.DATABASE_URL}' | base64 --decode
echo
 
kubectl get secret pganalyze-secret \
  -o jsonpath='{.data.LICENSE_KEY}' | base64 --decode
echo

If any values need to be corrected or updated, include all values — existing and new — in a single command:

kubectl create secret generic pganalyze-secret \
  --from-literal=DATABASE_URL=postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE \
  --from-literal=LICENSE_KEY=KEYKEYKEY \
  --dry-run=client -o yaml | kubectl apply -f -

Once resolved, re-run the self-check command before proceeding.

Step 6: Update the deployment manifest

Open your pganalyze-enterprise.yml file and update the image tag to the new version:

image: 'pganalyzeregistry.azurecr.io/pganalyze-enterprise:[new version]'

Step 7: Redeploy

Apply the updated manifest with the new image version:

kubectl apply -f pganalyze-enterprise.yml

Then scale the deployment back up to 1 replica:

kubectl scale deployment pganalyze --replicas=1

Confirm the rollout completes successfully:

kubectl rollout status deployment pganalyze

And verify the pod is running:

kubectl get pods -l app=pganalyze

At this point the upgrade is complete and the pganalyze UI should be accessible as expected.

Recovering from a failed upgrade

Scale down the deployment if it is not already at zero:

kubectl scale deployment pganalyze --replicas=0

Restore the statistics database from the backup taken in Step 1. Once the restore is complete, update pganalyze-enterprise.yml to reference the old image version and redeploy:

kubectl apply -f pganalyze-enterprise.yml

Then scale the deployment back up:

kubectl scale deployment pganalyze --replicas=1

Confirm the pod is running and healthy before investigating what went wrong with the upgrade.