Enterprise Server: Upgrade Amazon EKS

These are the upgrade instructions for pganalyze Enterprise Server for a Kubernetes cluster managed by Amazon EKS.

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 Amazon RDS 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 ECR

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 AWS container registry, replacing ACCOUNTID with your AWS account ID and REGION with your AWS region (e.g. "us-west-1"):

aws ecr get-login-password --region REGION | docker login --username AWS --password-stdin ACCOUNTID.dkr.ecr.REGION.amazonaws.com

Tag and push the new image, replacing ACCOUNTID, REGION, and VERSION:

docker tag quay.io/pganalyze/enterprise:[new version] \
  ACCOUNTID.dkr.ecr.REGION.amazonaws.com/pganalyze-enterprise:[new version]
 
docker push ACCOUNTID.dkr.ecr.REGION.amazonaws.com/pganalyze-enterprise:[new version]

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 ACCOUNTID, REGION, and VERSION with the appropriate values:

kubectl run pganalyze-migrate --rm -i \
  --image=ACCOUNTID.dkr.ecr.REGION.amazonaws.com/pganalyze-enterprise:[new version] \
  --restart=Never \
  --overrides='{
    "spec": {
      "containers": [{
        "name": "pganalyze-migrate",
        "image": "ACCOUNTID.dkr.ecr.REGION.amazonaws.com/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 ACCOUNTID, REGION, and VERSION:

kubectl run pganalyze-selfcheck --rm -i \
  --image=ACCOUNTID.dkr.ecr.REGION.amazonaws.com/pganalyze-enterprise:[new version] \
  --restart=Never \
  --overrides='{
    "spec": {
      "containers": [{
        "name": "pganalyze-selfcheck",
        "image": "ACCOUNTID.dkr.ecr.REGION.amazonaws.com/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 database connection... Success!
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: 'ACCOUNTID.dkr.ecr.REGION.amazonaws.com/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.