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: Audit Extensions Regularly Especially before major version upgrades. Limit Extensions via azure.extensions Only enable what you actively use. Clean Up Deprecated Extensions Remove unused or legacy extensions before they accumulate. Align with Azure's supported extension list 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
