Azure PostgreSQL Lesson Learned#11: Major Version Upgrade Failure Due to Unsupported Extensions

Co-authored with HaiderZ-MSFT​ 

Symptoms: How the Failure Appears

When attempting a Major Version Upgrade in Azure Portal, customers typically encounter upgrade fails immediately or gets stuck and sometimes, portal error indicating unsupported extensions detected

This is an expected behavior as Azure validates extension compatibility before performing any in‑place upgrade.

Root Cause: Unsupported PostgreSQL Extensions Block MVU

Azure Database for PostgreSQL Flexible Server only supports a specific list of extensions during major version upgrades. If your source server contains any extension outside that allowlist, the major version upgrade will be blocked.

Step-by-Step Troubleshooting & Resolution Guide

STEP 1 — Audit All Extensions on the Server

Azure PostgreSQL does not allow cross-database queries, so you must inspect each database individually.

➤ Option A: Check Extensions in Current Database

SELECT

current_database() AS database_name,

extname AS extension_name,

extversion AS version

FROM pg_extension;

➤ Option B: Auto-Generate Extension Check Queries for All Databases

SELECT

'SELECT ''' || datname || ''' AS database_name, extname, extversion

FROM pg_extension ORDER BY extname;' AS query_to_run

FROM pg_database

WHERE datistemplate = false;

Copy the generated queries and run them to produce a server-wide extension inventory.

👉 If ANY unsupported extension appears, the upgrade will fail.

STEP 2 — Remove Unsupported PostgreSQL Extensions

To unblock the Azure PostgreSQL MVU:

DROP EXTENSION IF EXISTS <extension_name> CASCADE;

⚠️ The CASCADE option may drop dependent objects — always verify impact prior to execution.

STEP 3 — Validate Allowed Extensions in Server Parameters

In Azure Portal:

Server → Server Parameters → azure.extensions

• Ensure only supported extensions are listed
• Remove or correct unsupported entries

Reference: Allow extensions

STEP 4 — Re-Run MVU

With unsupported extensions removed and supported ones validated:

• The server was in Ready state
• Free storage exceeded Azure’s 10–20% pre‑upgrade requirement
  Major Version Upgrades - Azure Database for PostgreSQL | Microsoft Learn

Trigger MVU again via Portal:

Portal → Server → Overview → Upgrade

Select your target PostgreSQL major version.
If all extension issues are resolved, the upgrade completes successfully.

Final Outcome

After removing unsupported PostgreSQL extensions and validating the azure.extensions parameter:

• ✔️ MVU completed without errors
• ✔️ Server upgraded to the desired PostgreSQL version

Best Practices to Avoid Future Upgrade Failures

These recommendations help maintain a healthy Azure PostgreSQL Flexible Server environment:

1. Audit Extensions Regularly Especially before major version upgrades.
2. Limit Extensions via azure.extensions Only enable what you actively use.
3. Clean Up Deprecated Extensions Remove unused or legacy extensions before they accumulate.
4. Align with Azure's supported extension list
5. Automate Extension Validation This reduces last-minute deployment surprises.

Helpful References

• Concepts - Major Version Upgrades in Azure Database for PostgreSql 
• Major Version Upgrades in Azure PostgreSQL
• PostgreSQL Extensions on Azure