Grafana upgrade rollback: how to plan a way back before you upgrade
A rollback is only as good as the backup taken before the upgrade and the downgrade path the release allows. For a self-hosted Grafana team, that means deciding before the change window what you will restore, from which copy, and whether the target version can read what the new version wrote. Treat the way back as a restore from a verified backup, not a reinstall of the older package, because Grafana writes schema changes and other state into its database during startup, and an older binary will not undo them. Grafana's guidance is to back up the database, the modified configuration files and the plugin folders together, so that the database, settings and plugin versions roll back as one set.
Plan the upgrade path first. Grafana's upgrade guidance describes major releases once a year in April or May, minor releases every other month and patch releases at least monthly. Each minor release is supported for 9 months and the last minor of a major version for 15 months, so a team that falls behind loses vendor support for the version it runs. Move one minor release at a time, apply patch releases on your normal cadence, and read the release notes for each step. Confirm the current support dates for your version in Grafana's upgrade guidance before you schedule the change, since support windows are the first input to how long you can wait.
This page covers three things: how to back up grafana.db or your MySQL or PostgreSQL database, how to capture grafana.ini, provisioning files and plugin folders, and where downgrades break. The main traps involve RBAC changes and secrets encryption. If a release has moved secrets to a new encryption scheme, reverting may require running the secrets rollback command before the older version starts, and that step needs to be rehearsed on a copy of your instance. Confirm which migrations your target release performs by reading its technical notes, then test the full restore on a non-production instance before you rely on it.
Which release changes make a rollback harder
This table lists the Grafana release changes that most affect whether you can return to an earlier version, with the impact on rollback and the action to take before upgrading. Read each row against the release notes for your exact target version, since the supplied release facts do not describe every change in detail. The main takeaway is that a verified database backup and a recorded secrets encryption state matter more than the version number itself.
| Change | Impact on rollback | Action needed before upgrading |
|---|---|---|
| Grafana 12.0.0 major release (May 5, 2025) | Major releases can change database schema and stored objects, so an older binary may not start cleanly against the upgraded database without restoring a backup. | Take a full database backup and confirm the release notes for 12.0.0 and every later major you pass through. |
| Grafana 13.0 and 13.x line (13.1.0 on July 1, 2026; 13.2.0 on August 18, 2026) | Unified storage migration for dashboards and folders makes a plain binary downgrade unreliable, so rollback depends on restoring the pre-upgrade database. | Back up grafana.db or your MySQL or PostgreSQL database, plus configuration and plugin folders, and confirm the 13.x release notes for your target minor. |
| Annual major release cadence (April or May each year) | Each major can bundle schema, RBAC and plugin changes, so a rollback plan written for one major may not cover the next. | Keep a dated backup for each upgrade step and review the upgrade guide before planning the next major. |
| Secrets encryption changes | Data source credentials and other secrets may be stored in a format an older version cannot read. Downgrading below Grafana 9.0 may require the secrets migration rollback command. | Record your current encryption state and the secret key, and confirm with the database encryption docs whether the rollback command applies to your version. |
| RBAC changes (RBAC always on from Grafana 10) | Permission data written by a newer version may not map back to older role definitions, so users can gain or lose access after a downgrade. | Export role and permission assignments, test a restore in a non-production copy, and confirm the RBAC notes for your target release. |
| Patch and minor releases (for example 13.2.4, 13.1.8 and 13.0.11 on October 13, 2026) | Patches often carry fixes that are not in earlier minors, so downgrading to a previous patch can reopen known defects even when the database is compatible. | Record the exact build before upgrading and confirm which patch level you intend to return to if you roll back. |
| Database engine version (SQLite, MySQL 8.0 or later, PostgreSQL 12 or later) | A database upgrade made alongside Grafana is harder to reverse than a Grafana upgrade alone, and a restored backup must match the engine version used to create it. | Upgrade Grafana and the database in separate steps, and confirm the database version your target release requires. |
What to back up before the upgrade
A rollback is only as good as the copies taken before the upgrade starts. The cards below cover the database, configuration, plugins and provisioning files, which together let you return to the previous state.
The Grafana database
The database holds dashboards, data source definitions, users, teams, folders and alert state. For SQLite, back up the single grafana.db file after stopping Grafana so the copy is consistent. For MySQL or PostgreSQL, take a database-native dump or backup while Grafana is idle. A database backup is what makes a rollback possible. Confirm the backup can be restored into a test instance before you rely on it.
Stop Grafana before copying SQLite
Copying grafana.db while the server is writing can produce a file that looks valid but is internally inconsistent. Stop the Grafana service, copy the file, then start the service again. Record the exact Grafana version in use before stopping it, so the backup is labeled with the release it came from. Plan a short maintenance window for this step on any instance people use during working hours.
Modified configuration files
Keep a copy of grafana.ini and any environment overrides, reverse proxy settings and secrets references that differ from defaults. These files control the database connection, authentication, cookie and security settings, and the paths Grafana reads on startup. Store the copies with the version they belong to, so a downgrade starts from the same settings that worked before.
Plugin folders
Back up the plugin directory, usually /var/lib/grafana/plugins on package installs, including any private or signed plugins your team built. Record each plugin's name and version, because a downgrade may restore plugins that the older Grafana release cannot load or that conflict with newer ones. Check which plugins the upgrade changes before you copy them, so the snapshot matches the pre-upgrade state.
Provisioning files
Data source, dashboard, plugin and alerting provisioning files define resources that Grafana loads at startup. Copy the provisioning directory, and the dashboard JSON it points to, so you can recreate state if the database restore misses something. Keep these files in version control where possible, since they are the most reliable record of intended configuration. Compare them against the database after restore to find drift.
How to upgrade with rollback points
This sequence gives you a tested way back at every stage, so a failed Grafana upgrade becomes a restore decision instead of a rebuild. Each step ends with a rollback point you can name and verify.
Inventory and freeze the current state
Record the running Grafana version, the database engine and version (SQLite, MySQL or PostgreSQL), the configuration files, the provisioning folders, the plugin list with versions, and the authentication method in use. Freeze dashboard and alert rule changes for the window so the backup matches what you will test. The step is done when the inventory is written down and someone other than the author has reviewed it. Rollback point 1: the frozen inventory, which tells you what a restore must bring back.
Back up the database, configuration and plugins
Take a backup of the database, the modified configuration files and the plugin folders, as Grafana's backup guidance recommends. For SQLite, stop Grafana before copying the single grafana.db file. For MySQL or PostgreSQL, use your database's own backup tooling so the copy is consistent. Store the backup outside the Grafana host, with the encryption key or secrets material kept in a separate, controlled location. Rollback point 2: the backup set, which is only valid once it has been verified.
Verify the backup by restoring it elsewhere
Restore the backup onto a separate host or database and start a Grafana instance of the same version against it. Confirm that users can sign in, that dashboards and data sources load, and that alert rules are present. Record any file that did not come back, such as a plugin folder or a custom config file. The step is complete when the restored copy starts cleanly and the checks pass. Rollback point 3: a restore you have proven, so you know a plain database restore works for this instance.
Upgrade a test copy to the target version
Build a test instance from the verified restore and upgrade it to the target release using the same steps planned for production. Read the release notes for removed features, plugin changes and storage migrations that apply to your version path. Log every error, warning and migration message. The step produces a dated upgrade log and a list of items that need action before production. Rollback point 4: the test copy itself, which you can discard without affecting users.
Run checks on data sources, dashboards and alerts
Test each data source connection, open a representative set of dashboards across teams, and confirm alert rules evaluate and route notifications to test contact points. Check that plugins load and that provisioned resources reconcile with the files on disk. Compare the results with the pre-upgrade inventory. The step is done when every item on the checklist has a pass or a logged defect with an owner. Rollback point 5: the test results, which show whether a rollback would be needed for a specific component.
Upgrade production with the backup in place
Schedule the production change, repeat the backup immediately before the upgrade, and then install the target version using the same method as the test copy. Start Grafana, watch the logs for migration errors, and run the same checks used on the test copy. Keep the previous package and the pre-upgrade backup available until the go or no-go decision is made. Rollback point 6: the pre-upgrade backup, taken after the freeze and before the change.
Make the go or no-go decision
Hold a short checkpoint with the owners of the service, the data sources and the alerting before the change is closed. Go if the checks pass and users can work normally. No-go if there is a data, login or alerting failure that the team cannot fix within the agreed window. For a plain database restore, the rollback works when the target version is the one the backup came from and no irreversible storage migration blocks it. If the upgrade changed secrets encryption and the backup was taken before that change, you may also need the secrets migration rollback command, so confirm this against the database encryption guidance before the change. The checkpoint closes with a recorded decision and the retention date for the backup.
Where downgrades fail: RBAC, secrets encryption and database schema
Downgrading Grafana is harder than restoring a backup, because a newer version can change what the older binary is able to read. Three areas cause most of the trouble: the permission model, the way secrets are encrypted, and the database schema. Grafana 10 made role-based access control always on, so a Grafana 9.x or earlier binary may not interpret permissions written by the upgraded instance the way you expect. Check the Grafana 10 release notes for your exact source and target versions before assuming a restored database will give the same access.
Secrets encryption is the trap most likely to block a rollback outright. The grafana cli admin secrets-migration rollback command returns secrets to legacy encryption, and Grafana's database encryption documentation says this may be needed to downgrade below Grafana 9.0. Run the migration status check and record which secrets are stored under which scheme before the upgrade. Data source passwords, alerting contact point credentials and plugin settings are the items to confirm in your own instance, since a restored database that still holds re-encrypted values can leave an older binary unable to decrypt them.
Schema changes are the third trap. A newer Grafana can add or alter tables during startup migration, and an older binary may refuse to start against that schema or fail on a query it does not understand. This is why the backup has to be a database snapshot taken while Grafana is stopped, not a copy of configuration files alone. For a MySQL or PostgreSQL backend, confirm the exact database engine version your target release supports, since a database major upgrade adds a separate rollback path. Rehearse the full downgrade on a copy of production data, including the secrets rollback and a login test with each role, and treat any failed step as a reason to stop and revise the plan.
How the database choice changes the rollback plan
The database you run Grafana on decides what a backup looks like and how far back you can go. Each engine has its own copy procedure, support window and failure mode, so the rollback plan starts with identifying which one you operate.
SQLite as a single file
SQLite keeps Grafana's configuration in one grafana.db file. Stop Grafana before copying the file, because copying it while the service writes can produce a backup that will not restore cleanly. Keep the copy alongside the configuration files and plugin folders you back up at the same time, and test that Grafana starts from the copy on a separate host. The SQLite default is suitable for evaluation, but it is not a production choice, so the rollback plan for a production instance will almost always involve MySQL or PostgreSQL.
Production and HA need a server database
The Grafana installation docs state that SQLite does not scale for production, so MySQL or PostgreSQL is required for production and high availability. Two or more active-active Grafana servers share one of these databases behind a load balancer. For rollback, this means the database is shared state across every node, so a backup has to capture the whole database rather than a file from one Grafana host, and every node must be stopped or drained consistently before you restore.
MySQL 8.0 or later
Grafana supports MySQL 8.0 or later as its configuration store. Take a logical or physical backup with the tooling your MySQL team already uses, and confirm that the backup restores into the same MySQL major version you will keep running. The MySQL reference manual describes an LTS track with long support and an Innovation track supported only until the next Innovation release, so confirm which MySQL line your environment is on before you plan a database upgrade alongside the Grafana upgrade.
PostgreSQL 12 or later
Grafana supports PostgreSQL 12 or later. Use pg_dump or pg_dumpall for a logical copy, or continuous archiving for point-in-time recovery, and rehearse the restore on the same major version. Check the PostgreSQL support window before you pick a rollback target. Versions 14 and 15 are close to end of support, so a database that stays on an unsupported release can limit the rollback options you can safely keep. Record the database version in the change record next to the Grafana version.
Database and Grafana upgrades separately
A Grafana upgrade and a database engine upgrade are two changes, and each needs its own rollback decision. If you move PostgreSQL to a new major version in the same window, a Grafana downgrade will not undo the database change, and a database restore will not undo the Grafana schema migration. Schedule them apart where possible, take a backup immediately before each change, and write down which backup restores which version pair.
What makes a rollback plan take longer
How does database size and engine change the time needed to roll back Grafana?
The database engine and its size decide how long a backup takes, how long a restore takes, and how much you can test before the upgrade. A single SQLite file is copied while Grafana is stopped, so the backup window is set by file size and disk speed. A MySQL or PostgreSQL database is usually backed up with the database's own tools, which adds dump or snapshot steps, storage for the copy, and a restore test on a separate instance. Larger databases also make a dry-run restore longer, which is why many teams rehearse the restore before they schedule the upgrade. Confirm the backup method and retention with your database team before you start.
Why does the number of data sources and plugins affect rollback verification?
Every data source and plugin you rely on has to be checked after a restore, because a restored database can bring back settings that point to services, credentials or plugin versions that no longer match the running binary. Plan a verification list that covers each data source connection, each dashboard family that depends on it, and each plugin version recorded before the upgrade. The longer that list, the more time the post-restore check takes. Plugins installed in the plugin folder also need to be backed up with the database, since the database alone does not restore them.
How do custom configuration and provisioning files lengthen a rollback?
Custom grafana.ini settings, environment variables, and provisioning files for data sources, dashboards, plugins and alerting are outside the database, so each one must be captured separately. Provisioned resources are loaded at startup, which means a rollback can reload an older file set, and a file that was changed for the newer version may not match the older binary. Keep the configuration under version control where possible, record which files changed during the upgrade, and check whether any provisioned object was edited through the UI, because those edits can be overwritten on restart.
Does running Grafana in high availability make rollback harder?
Yes. In a high availability setup, two or more active servers share one MySQL or PostgreSQL database, so a rollback must stop every node, restore the shared database once, and bring back the same binary version on all nodes. Mixed versions running at the same time can share the database during a partial rollback, which creates risk that is hard to reverse. Plan the rollback as a fleet operation, decide how the load balancer will drain nodes, and confirm how alerting is set up so that notifications are not duplicated during the switch.
What happens to a rollback plan when secrets encryption is enabled?
Enabled secrets encryption is one of the most significant drivers, because encrypted values in the database may only be readable by the version that wrote them. The Grafana database encryption docs describe a secrets migration rollback command that returns secrets to legacy encryption, which may be needed to downgrade below Grafana 9.0. Ask whether the encryption key location is backed up with the database, whether the rollback command has been tested on a copy, and which data source credentials and alert contact secrets depend on it. Treat this as a separate test step, not a footnote.
How does access to a test environment shape the rollback timeline?
A rollback plan is only as strong as the place where it was tested. Without a staging copy that matches production in version, database engine, plugins, provisioning files and data source endpoints, the first real test of the restore happens during an outage. A test environment lets you restore the backup, run the verification list, and time the steps. Confirm whether your organization can provision a non-production instance that connects to test data sources, how long access requests take internally, and who approves the change window. Infrastructure access and approvals often take longer than the technical restore.
Who should own the rollback steps, and what can a partner take on?
Ownership splits between the Grafana operator, the database administrator, the platform team that owns infrastructure and backups, and the owners of the data sources and dashboards. Internal teams usually keep control of production change approval and access, while an implementation partner can plan the backup set, write the rollback runbook, rehearse the restore in a test environment and document the verification checks. DeployOpen works in your own infrastructure under a written, fixed scope, so the split of responsibilities should be agreed before work starts and reflected in the quote.
What DeployOpen needs from your team to plan a safe rollback
Before DeployOpen can plan a way back, we need to know exactly where you are and where you are going. Send the current Grafana version and the target version, and the release notes you are working from. Name the database engine behind the instance: SQLite with a grafana.db file, MySQL or PostgreSQL. For MySQL or PostgreSQL, we need the host layout, the account Grafana uses, and who can take a backup and restore it to a separate host. The database is the part of a rollback that cannot be reconstructed from files, so its access path is the first question in the plan.
Next, describe how Grafana is deployed: operating system packages, Docker images, a Helm chart on Kubernetes, or a configuration management tool. Each method changes where the configuration file, the plugin folder and the image tag live, and therefore what has to be captured before the upgrade. Provide a plugin inventory with installed versions and whether each plugin was installed from the catalog, from a local archive or from a private repository. Also state whether provisioning files, Terraform or Git-based sync manage data sources, dashboards, plugins or alert rules, because a restored database that disagrees with the files on disk can cause confusion during a downgrade. Ask your team to confirm whether any secrets encryption migration has run on the instance.
Finally, give us the maintenance window you can offer, including who has authority to stop Grafana and approve a rollback decision, and the period during which dashboards or alerts can be unavailable. Our work is fixed-scope: we agree the scope, deliverables and timeline in writing before any change is made to your environment. DeployOpen plans, tests and documents the backup and restore procedure, but we do not issue audit reports or attestations. If a rollback plan supports a compliance assessment, the evidence should be reviewed and attested by an independent auditor or certification body that your organization selects.
How DeployOpen scopes, delivers and supports Grafana upgrades
DeployOpen plans the way back before any Grafana upgrade touches production. We scope the backup and rollback path for your database, configuration and plugins, build and rehearse it in your own infrastructure, and hand over a runbook your team can execute under pressure.
How we scope
- Engagements are fixed-scope, with the rollback path, deliverables and timeline agreed in writing before work starts.
- We confirm which database backs your Grafana instance, whether SQLite, MySQL or PostgreSQL, and which backup method it supports.
- We inventory modified configuration files, provisioned resources and plugin folders that a rollback would need to restore.
How we build
- We write and test backup procedures for grafana.db or your MySQL or PostgreSQL database, stopping Grafana before any SQLite copy.
- We rehearse a downgrade in a non-production copy, checking RBAC, user identities and secrets encryption behavior before go-live.
- We confirm the secrets-migration rollback path and its version limits with the Grafana documentation for your target release.
How we hand over
- You receive a written rollback runbook with backup, restore and downgrade steps, owners and verification checks for each step.
- The handover covers documented decision points, such as when to roll back and when to fix forward instead.
- We document configuration, plugin versions and database backup evidence so your team can repeat the process without us.
How we support
- Ongoing support, upgrade assistance and continuous testing are available as retainers after the initial engagement.
- A retainer can cover re-testing the rollback path for each new minor or patch release your team plans to adopt.
- Ask any provider, including us, to confirm in writing which recovery steps are included and which remain your responsibility.
