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 AzureAzure PostgreSQL Lesson Learned #13: Major Version Upgrade Failure Due to HypoPG Extension
Co-authored with angesalsaa Case Overview We investigated a customer case where a Major Version Upgrade (MVU) from PostgreSQL 11 to 17 on Azure Database for PostgreSQL Flexible Server consistently failed during the pre-check phase. The upgrade was triggered through the Azure Portal, but the process was blocked due to the presence of the HypoPG extension installed across multiple databases. Symptoms: How the Failure Appears When attempting a Major Version Upgrade in Azure Portal, customers typically encounter: Immediate failure during pre-check validation. Portal error indicating failed at pre-check. Upgrade does not proceed beyond validation. This is expected behavior because Azure validates extension compatibility before performing any in-place upgrade. Root Cause: HypoPG Extension Blocks MVU Azure Database for PostgreSQL Flexible Server supports only a specific list of extensions during major version upgrades. HypoPG is not part of the allow-listed extensions for MVU. If your source server contains HypoPG in any database, the upgrade will fail. 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; 👉 In our case, HypoPG appeared in 4 databases, causing the pre-check failure. STEP 2 — Enable HypoPG Temporarily in Azure Portal Before removing the extension, we had to re-enable HypoPG in Server Parameters because it was previously disabled at Azure Portal level as customer disabled as precaution step but removing part was not enough here: Azure Portal → Server → Server Parameters → azure.extensions → Add hypopg STEP 3 — Remove HypoPG Extension from All Databases Once enabled the extension, remove the extension from each affected database using following command: DROP EXTENSION hypopg CASCADE; ⚠️ CASCADE will drop dependent objects verify impact before execution. After running this command on all affected databases, HypoPG was successfully removed. STEP 4 — Validate Allowed Extensions In Azure Portal: Server → Server Parameters → azure.extensions Ensure only supported extensions are listed. Remove unsupported entries. Make sure hypopg is removed STEP 5 — Re-Run MVU With HypoPG removed and supported extensions validated: Server was in Ready state. Trigger MVU again via Portal: Portal → Server → Overview → Upgrade → Select PostgreSQL 17 Upgrade completed successfully. a { text-decoration: none; color: #464feb; } tr th, tr td { border: 1px solid #e6e6e6; } tr th { background-color: #f5f5f5; } Final Outcome After removing HypoPG and validating the server parameters: MVU completed without errors. Server upgraded from PostgreSQL 11 to 17. Best Practices to Avoid Future Upgrade Failures 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 early. Align with Azure’s Supported Extension List — Check official documentation. Automate Extension Validation — Prevent last-minute surprises. Helpful References Major Version Upgrades | Microsoft Learn
