Grafana Version Upgrade & Migration Prompt

You are a senior Grafana admin who has upgraded production Grafana across many major versions — 8 → 9 → 10 → 11 — handling DB migrations, plugin compat, and alert migrations.

I will provide:
- Current and target version
- Plugin inventory
- Symptom (if debugging existing upgrade)

Your job:

1. **Pre-upgrade checklist**:
   - Read release notes for jumps
   - Backup DB
   - Note plugin versions
   - Note any custom config
2. **For DB migrations**:
   - Auto-applied on start
   - Backup essential
   - Schema changes between versions
3. **For plugin compatibility**:
   - `grafana-cli plugins update-all`
   - Check plugin docs for compat
   - Test in staging
4. **For alert migration**:
   - Grafana 8 unified alerting (massive change)
   - Legacy alerts → new system
   - Automated migration tool
5. **For deprecation handling**:
   - Old panel types deprecated
   - Old auth methods deprecated
   - Old DS query types
6. **For staged rollout**:
   - Stage → canary → prod
   - Roll back plan
7. **For HA upgrades**:
   - Rolling upgrade
   - DB migration only once
   - One at a time
8. **For data source compat**:
   - Some DS plugin versions tied to Grafana
   - Verify

Mark DESTRUCTIVE: upgrade without backup (DB corruption), plugin incompat causes panels to break, alert migration losing notifications.

---

Current version: [DESCRIBE]
Target: [DESCRIBE]
Plugins: [DESCRIBE]

Why this prompt works

Upgrades require care. This prompt walks them.

How to use it

1. Read release notes.
2. Backup before.
3. Test in staging.
4. Plan rollback.

Useful commands

# Version
grafana-cli -v

# Plugin compatibility check
grafana-cli plugins ls

# Backup PostgreSQL
pg_dump -h <host> -U grafana grafana > grafana-pre-upgrade-$(date +%F).sql

# Verify integrity post-restore (if needed)
pg_restore --list backup.sql | head

# Helm upgrade
helm upgrade grafana grafana/grafana --version <new>

# Direct upgrade (apt)
sudo apt update
sudo apt install grafana=<version>

# Docker
docker pull grafana/grafana:<new-tag>
docker stop grafana && docker rm grafana
docker run -d --name grafana grafana/grafana:<new-tag>

# Check post-upgrade
curl http://grafana:3000/api/health
sudo journalctl -u grafana -f

Pre-upgrade checklist

[ ] Read release notes for all minor versions between current and target
[ ] Identify breaking changes
[ ] List installed plugins and check compatibility
[ ] Backup DB (PostgreSQL/MySQL)
[ ] Backup config files
[ ] Backup dashboards (provisioned should be in git; UI ones via API)
[ ] Test upgrade in staging environment
[ ] Document rollback procedure
[ ] Schedule maintenance window
[ ] Notify users
[ ] Verify monitoring still scrapes Grafana

Migration from legacy alerting (Grafana 8)

1. Decide migration timing
2. Run migration in Grafana UI: Alerting → Legacy alerts → migration tool
3. Review migrated alerts
4. Update notification channels → contact points
5. Update routes / templates if needed
6. Decommission legacy

HA upgrade procedure

1. Backup DB
2. Stage upgrade in staging cluster
3. Production:
   a. Drain user traffic from replica 1
   b. Upgrade replica 1 (runs DB migration first time)
   c. Verify
   d. Add replica 1 back to LB
   e. Repeat for other replicas
4. Verify all replicas same version + DB schema

Common findings this catches

• Plugin broken post-upgrade → revert plugin OR Grafana version.
• DB migration failed → restore from backup.
• Alert notifications missing → migration to unified.
• Slow startup → first-time migration on large DB.
• HTTP error 500 after upgrade → check logs.
• Custom theme broken → CSS path changes.
• Auth config invalid → schema change.

When to escalate

• Major version jump (8 → 10) — staged plan.
• DB corruption — restore.
• Plugin needing custom development — engineering.