cmdb-insight/docs/POSTGRESQL-VERSION-UPGRADE.md

PostgreSQL Version Upgrade Guide

Guide for upgrading Azure PostgreSQL Flexible Server from version 15 to 18.

⚠️ Important Considerations

Before Upgrading

1. Backup: Azure automatically creates backups, but verify backups are working
2. Downtime: Major version upgrades require downtime (typically 5-15 minutes)
3. Application Compatibility: Ensure your application supports PostgreSQL 18
4. Extension Compatibility: Check if any PostgreSQL extensions are compatible with version 18

PostgreSQL 18 Changes

• Performance improvements: Better query optimization
• New features: Enhanced JSON support, improved partitioning
• Breaking changes: Some deprecated features removed
• Extension updates: Some extensions may need updates

---

🚀 Upgrade Process

Step 1: Check Current Version

az postgres flexible-server show \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --query "{name:name, version:version, state:state}" -o table

Step 2: Verify Backups

# List recent backups
az postgres flexible-server backup list \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --server-name zdl-cmdb-insight-prd-psql \
  --query "[0:5].{name:name, timeCreated:timeCreated}" -o table

Step 3: Schedule Maintenance Window

Recommended: Perform upgrade during low-traffic period or maintenance window.

Step 4: Perform Upgrade

# Upgrade to PostgreSQL 18
az postgres flexible-server upgrade \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --version 18 \
  --yes

What happens:

• Server will restart
• Database will be upgraded to version 18
• Downtime: ~5-15 minutes
• Existing data is preserved

Step 5: Verify Upgrade

# Check new version
az postgres flexible-server show \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --query "{name:name, version:version, state:state}" -o table

# Should show: version: "18"

Step 6: Test Application

# Restart backend app to reconnect
az webapp restart \
  --name zdl-cmdb-insight-prd-backend-webapp \
  --resource-group zdl-cmdb-insight-prd-euwe-rg

# Check logs for connection
az webapp log tail \
  --name zdl-cmdb-insight-prd-backend-webapp \
  --resource-group zdl-cmdb-insight-prd-euwe-rg

---

🔄 Alternative: Step-by-Step Upgrade (15 → 16 → 17 → 18)

If you prefer to upgrade incrementally:

# Upgrade 15 → 16
az postgres flexible-server upgrade \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --version 16 \
  --yes

# Wait for completion, then upgrade 16 → 17
az postgres flexible-server upgrade \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --version 17 \
  --yes

# Wait for completion, then upgrade 17 → 18
az postgres flexible-server upgrade \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --version 18 \
  --yes

Note: Direct upgrade from 15 → 18 is supported and recommended (faster, less downtime).

---

🛠️ Troubleshooting

Upgrade Fails

If upgrade fails:

1. Check server state:

   az postgres flexible-server show \
     --resource-group zdl-cmdb-insight-prd-euwe-rg \
     --name zdl-cmdb-insight-prd-psql \
     --query state -o tsv
   

2. Check logs:

   az monitor activity-log list \
     --resource-group zdl-cmdb-insight-prd-euwe-rg \
     --query "[?contains(operationName.value, 'upgrade')]" \
     --output table
   

3. Restore from backup if needed:

   # List available backups
   az postgres flexible-server backup list \
     --resource-group zdl-cmdb-insight-prd-euwe-rg \
     --server-name zdl-cmdb-insight-prd-psql
   

Application Connection Issues

If application can't connect after upgrade:

1. Verify connection string (should still work, no changes needed)
2. Check firewall rules (should remain unchanged)
3. Restart application to refresh connections
4. Check application logs for specific errors

---

📊 Monitoring

Check Upgrade Status

# Monitor upgrade progress
az postgres flexible-server show \
  --resource-group zdl-cmdb-insight-prd-euwe-rg \
  --name zdl-cmdb-insight-prd-psql \
  --query "{state:state, version:version}" -o json

Performance After Upgrade

Monitor performance metrics after upgrade:

• Query performance
• Connection times
• Resource usage

---

✅ Post-Upgrade Checklist

• Version upgraded successfully (verified)
• Application reconnected successfully
• All databases accessible
• Performance metrics normal
• No errors in application logs
• Backup system working

---

🔗 Related Documentation

• docs/AZURE-POSTGRESQL-SETUP.md - Initial PostgreSQL setup
• docs/AZURE-APP-SERVICE-DEPLOYMENT.md - App Service deployment

---

💡 Best Practices

1. Test in staging first (if you have a staging environment)
2. Schedule during maintenance window
3. Notify users about planned downtime
4. Monitor closely after upgrade
5. Keep backups for at least 7 days after upgrade

---

Note: PostgreSQL 18 is the latest version with improved performance and features. The upgrade is generally safe and recommended.