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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   # 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

```bash
# 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.