Upgrading Grafana shouldn't feel like a high-stakes gamble with your production metrics. If you're running a monitoring stack, moving to a newer version gives you critical security patches, query performance boosts, and better panel types. Yet, missing a single pre-flight check can break your dashboards or corrupt your SQLite database.
This guide walks you through the exact process to upgrade Grafana safely, preserve your configurations, and verify your dashboards post-migration without downtime scares.
Why Upgrading Grafana Matters
Staying current with your observability stack keeps your infrastructure secure and responsive. Older versions often suffer from unpatched vulnerabilities or slow dashboard render times when handling large time-series data sets.
When you move to recent releases, you gain access to optimized backend queries, finer-grained access control, and improved native alerting engines. But before you touch any package manager, you need a clear picture of your current environment.
Pre-Flight Checklist and Compatibility Checks
Never run an upgrade command blindly. Take ten minutes to map your current setup so you don't run into breaking changes between major versions.
Inspect Your Current Version
Check your running version by looking at the footer of your Grafana UI or by running a quick command in your terminal:
grafana-server -v
Review the official Grafana Changelog to spot any breaking changes or deprecated database schemas between your current version and your target version. Skipping major versions—such as jumping straight from v8 to v11—requires intermediate upgrade steps. Always step through major releases sequentially.
Back Up Critical Data and Configuration Files
Your dashboards, alert rules, and user preferences live in your backing database (SQLite by default, or MySQL/PostgreSQL in enterprise setups) and configuration files.
- Stop the Grafana service so no new writes occur during your backup window.
- Locate and copy your primary configuration file, typically found at
/etc/grafana/grafana.ini. - If you use the default SQLite database, back up the
.dbfile (usually located in/var/lib/grafana/grafana.db). - Export critical JSON dashboard definitions as a fallback safety net.
Step-by-Step Upgrade Process
The exact installation commands depend on your operating system and package manager. Below is the standard process for Linux environments using APT.
Step 1: Stop the Running Service
Prevent background processes from modifying data mid-upgrade:
sudo systemctl stop grafana-server
Step 2: Install the New Package
Update your local package lists and install the target version using your package manager:
sudo apt-get update
sudo apt-get install grafana
If you manage plugins, update them now to ensure compatibility with the new core version:
grafana-cli plugins update-all
Step 3: Run Database Migrations and Start Grafana
Grafana automatically handles schema migrations on startup, but you should always verify permissions and systemd daemon files before launching:
sudo systemctl daemon-reload
sudo systemctl start grafana-server
Check the service status to confirm it started cleanly:
sudo systemctl status grafana-server
Post-Upgrade Verification
Once the service runs, open your browser and navigate to your Grafana instance. Don't assume everything works just because the login page loads.
- Check your primary data sources (like Prometheus or Loki) by hitting the Save & Test button in your data source settings.
- Open high-traffic dashboards to confirm panels render without query errors.
- Inspect
/var/log/grafana/grafana.logfor any warning lines or database migration errors.
Common Mistakes to Avoid
- Skipping backups: Relying on hope instead of copying
grafana.dbbefore running apt-get. - Ignoring plugin compatibility: Running an outdated third-party panel plugin that crashes your UI on the new version.
- Jumping multiple major versions: Moving from v7 to v10 in one leap, which frequently breaks internal data models.
Frequently Asked Questions
Can I downgrade if something breaks?
Yes, if you kept a backup of your database file and the older package binary. Stop the service, restore your previous database backup, and reinstall the older package version.
Do my custom plugins get wiped during an upgrade?
Standard package managers leave /var/lib/grafana/plugins intact, but you should still verify your plugin directory permissions after the installation finishes.
How do I handle breaking changes in configuration files?
Compare your existing grafana.ini with the new sample configuration file provided by the installation package to incorporate new syntax options safely.
