Grafana 12 to 13 upgrade: when to move and the supported path
Teams running self-hosted Grafana 12.x need to plan the move to 13 as a change to storage and automation, not a routine patch. The upgrade migrates folders and dashboards from the legacy SQL tables into unified storage on startup, and it requires plugin and automation checks before the new version starts. Those checks decide whether the upgrade is a short window or an incident, so they belong in the plan before a date is set.
The release cadence explains why this move is worth scheduling deliberately. Grafana's upgrade guidance says major releases arrive once a year, in April or May, minor releases roughly every other month and patch releases at least monthly. Each minor release is supported for 9 months, and the last minor release of a major version for 15 months. Confirm the current support dates for your running minor in the when to upgrade guidance before you commit to a window, since a 12.x minor that falls out of support changes the urgency.
The supported path starts from the latest 12.x patch, so that any fixes in your current minor are in place before the major jump. Do not start from 13.0.0. That release was withdrawn after a migration bug could lose or revert dashboards and folders on self-managed instances upgraded from 12.x with Git Sync feature flags enabled, and the fix shipped in 13.0.1. Target 13.0.1 or later, check the release notes for the newest 13 patch, and confirm with your own change record which build you are approving. Use the Grafana 13.0 upgrade guide as the reference for that sequence.
What changes in Grafana 13 and what each change requires
This table lists the Grafana 13 changes that affect self-hosted upgrades from 12.x, what each one does to your instance, and the action to take before or after the upgrade. Read it as a checklist: rows that involve storage, plugins or automation need work before you start the upgrade, not after it.
| Change | Impact | Action needed |
|---|---|---|
| Folders and dashboards move to unified storage | Grafana migrates folders and dashboards from legacy SQL tables to unified storage on startup, so the migration runs as part of the upgrade. | Back up the database before upgrading. Rolling back later requires restoring that backup, not just reinstalling the older version. |
| grafana-cli and grafana-server removed | The deprecated grafana-cli and grafana-server commands no longer exist in Grafana 13. | Replace them with grafana cli and grafana server in systemd units, scripts, container entrypoints and automation. |
| Numeric-ID data source APIs disabled | Data source APIs that address sources by numeric ID are disabled by default. | Find scripts, provisioning jobs and integrations that call these APIs, and switch them to UID-based calls before the upgrade. |
| React 19 plugin requirements | Grafana 13 moves to React 19, so plugins built for earlier React versions may fail or misrender. | Update every plugin to a version compatible with React 19 before upgrading, and confirm each one loads in a test instance. |
| Migration bug in 13.0.0 with Git Sync | On self-managed instances upgraded from 12.x with Git Sync feature flags enabled, 13.0.0 could lose or revert dashboards and folders. | Do not use 13.0.0. Upgrade to 13.0.1 or later, and confirm your Git Sync feature flag settings before starting. |
What to prepare before touching the production instance
Six preparation items cover the state you must know before Grafana 13 changes anything on startup. Together they establish a restore point, the plugins and automation that will break, the Git Sync exposure, a rehearsal environment and a named decision owner. Complete them in a staging copy first, then repeat them against production on the day of the change.
Verified database backup
Take a backup of the database Grafana uses for configuration, not just the file copy you assume exists. For SQLite that is the grafana.db file, taken with Grafana stopped or with a consistent snapshot. For MySQL or PostgreSQL, use the database's own dump or snapshot tooling. Restore the backup to a scratch host and confirm dashboards and folders appear. Grafana 13 migrates folders and dashboards to unified storage at startup, and rolling back requires this exact backup, so an untested file is not a restore point.
Plugin React 19 inventory
List every installed panel and data source plugin with its installed version, its source (Grafana catalog, private build or community) and whether a React 19 compatible release exists. The 13.0 upgrade guide recommends updating all plugins before upgrading as part of the move to React 19. Plugins that cannot be updated, including abandoned community plugins and internal builds that were never rebuilt, become the blocking items for the go decision and need an owner and a replacement plan.
Numeric data source ID callers
Search dashboards, alert rules, provisioning files, scripts, Terraform modules and CI jobs for calls that address data sources by numeric ID. Data source APIs that use numeric IDs are disabled by default in Grafana 13, so any caller that still uses them will fail after the change. Convert these callers to data source UIDs in staging and confirm each one returns the expected result. Record every owner, because automation teams are often outside the group that runs Grafana.
Legacy CLI and server commands
Find every job that invokes grafana-cli or grafana-server directly, including systemd units, container entrypoints, configuration management roles, Helm hooks and backup or plugin install scripts. These commands were deprecated since Grafana 10.0 and are removed in Grafana 13 in favor of grafana cli and grafana server. Update each invocation in the source repository, not only on the host, so a rebuild does not reintroduce the old names. Run each updated job once in staging to confirm exit codes.
Git Sync feature flag status
Check the configuration and feature toggles on the current instance to see whether any Git Sync feature flags are enabled. The 13.0 upgrade guide warns that a migration bug in 13.0.0 could lose or revert dashboards and folders on self-managed instances upgraded from 12.x with these flags enabled. Confirm the exact fix version you will install, because 13.0.0 was withdrawn and the fix shipped in 13.0.1. If flags are enabled, treat the upgrade as a separate, slower change with its own rollback test.
Go or no-go approvers
Name the people who can approve the production change and the person who can halt it, and write the criteria down before the window opens. Typical approvers include the Grafana platform owner, the security or compliance contact for audit evidence, and a representative for teams whose dashboards or alerts depend on this instance. Agree the rollback trigger in advance, including who restores the backup and how long dashboards may remain unavailable. A decision made during the window without these roles defined tends to default to proceeding.
Which upgrade path fits your instance
Grafana stores configuration in SQLite by default, and the installation documentation states that SQLite does not scale for production. An instance on SQLite is therefore most likely a test, lab or evaluation environment, and the upgrade path should reflect that. Because there is one process and one local database file, the upgrade is mostly a question of stopping Grafana cleanly, copying the database file and then starting the new binary so the migration can run on startup.
- Stop the service before copying: Confirm Grafana is fully stopped so the database file is not changing while you copy it.
- Back up the database file: The 13.0 upgrade guide says that rolling back requires restoring the database backup taken before the upgrade, so keep a verified copy of the SQLite file with the matching configuration and plugin directory.
- Update plugins first: Update all plugins on the current 12.x version before changing the binary, as the upgrade guide recommends for the React 19 move.
- Watch the first startup: The folder and dashboard migration to unified storage runs on startup, so review the logs before users return.
- Plan a production move separately: Moving the data to MySQL or PostgreSQL is a migration in its own right, so do not combine it with this upgrade.
Before proceeding, confirm the 13.0 migration steps and the current minimum requirements for your target version in the Grafana 13.0 upgrade guide.
A single Grafana server on MySQL 8.0 or later, or PostgreSQL 12 or later, is the usual production starting point before high availability is added. The main difference from the SQLite case is that the database is a separate service with its own backup process. The rollback plan depends on that database backup, so the database team needs to be part of the upgrade window, not just the Grafana team.
- Take a logical or snapshot backup of the database: Coordinate with the database owner so the backup is consistent and restorable, and test a restore before the upgrade window opens.
- Record the current configuration and plugin versions: Store the
grafana.inifile, provisioning files and the installed plugin list so you can return to the same state. - Drain user activity where possible: Announce a window and stop scheduled exports or API automation that writes dashboards, since the storage migration changes where folders and dashboards live.
- Upgrade and verify: Install the target 13.x package or image, start Grafana, then check that folders, dashboards and data sources load as expected.
- Confirm package and image paths: Check the installation documentation for the packaging method you use, since the command names changed in 13.0.
Before proceeding, confirm your database version against the supported versions in the installation documentation and read the 13.0 upgrade guide for the database-related steps.
High availability uses two or more active-active Grafana servers behind a load balancer, sharing a MySQL or PostgreSQL database. The shared database means the storage migration runs once against shared tables, so the sequence has to protect that single migration from being started by several nodes in different versions at the same time. The documentation also notes that alerting needs extra configuration to avoid duplicate notifications and that Grafana Live has limitations in HA, so verify those behaviors after the upgrade.
- Drain one node at a time: Remove a node from the load balancer, upgrade it and confirm it is healthy before returning it to rotation.
- Upgrade one node first: Start the first upgraded node and let the storage migration complete while the other nodes stay on 12.x, after confirming that mixed-version operation is supported for this path in the upgrade guide.
- Confirm the database backup and rollback path: A rollback means restoring the database backup taken before the upgrade, which affects every node at once, so agree on the decision point in advance.
- Check alerting and sessions: Verify that only one node sends each notification and that users can reach any node with database-backed auth tokens.
- Upgrade the remaining nodes: Bring the other nodes into the new version one by one, checking the load balancer health checks at each step.
Before proceeding, confirm the supported mixed-version behavior and the HA limitations in the high availability documentation and the 13.0 upgrade guide.
How to sequence the upgrade with checks and rollback points
This sequence moves a self-hosted Grafana 12.x instance to 13 in an order where each stage has a verifiable check and a restore point. Each step ends with evidence that the next step can rely on, so a failure at any stage stops the change before production data is affected.
Update to the latest 12.x patch
On your current 12.x line, install the latest patch release before any 13 work starts, so the starting point includes available fixes. The platform team confirms the running version on the server and compares it with the grafana/grafana releases page. Keep the existing 12.x package or image tag available so the same version can be reinstalled if the patch causes a regression. Done means the running version is recorded and the instance is stable for a full business cycle.
Update all plugins and confirm React 19 support
The plugin owner reviews every installed plugin, checks its release notes for React 19 support, and updates it on 12.x. Abandoned community plugins and any Angular-based panels are flagged for replacement, since the upgrade guide asks for all plugins to be updated before the move to React 19. Keep a copy of the previous plugin directory so you can restore it if an update breaks panels on 12.x. Done means a list of plugins with versions and support status exists, and no plugin is marked as unsupported.
Inventory numeric-ID and CLI usage
The automation owner searches dashboards, provisioning files, scripts, CI jobs and infrastructure code for two patterns. The first is data source API calls that use numeric IDs, which 13 disables by default. The second is calls to grafana-cli and grafana-server, which are removed in favor of grafana cli and grafana server. Each match is changed to use data source UIDs and the new command forms, and tracked in version control. Done means a reviewed change list exists, with an owner for each item, and the changes pass on the 12.x instance before the upgrade.
Verify Git Sync feature flags before choosing a target
The Grafana platform owner records whether any Git Sync feature flags are enabled on the 12.x instance, in configuration files and in environment variables. The 13.0 upgrade guide warns that 13.0.0 could lose or revert dashboards and folders on self-managed instances upgraded from 12.x with these flags enabled, and that the fix shipped in 13.0.1. If flags are enabled, the target is 13.0.1 or a later patch, never 13.0.0, and the flag handling is confirmed against the upgrade guide. Done means a signed record of the flag state and the chosen target version exists.
Take and restore-test the database backup
The operations owner takes a backup of the database Grafana uses, which is grafana.db for SQLite or the MySQL or PostgreSQL database for other setups. The backup also covers configuration files and the plugins directory. To verify it, restore the backup to a separate instance or database and compare folder and dashboard counts with the live instance. Record the timestamp and a checksum for the backup. This backup is the rollback point, because the upgrade guide says that returning to an earlier version requires restoring it, not only reinstalling the old package. Done means a restore test has passed.
Upgrade staging and run dashboard and alert checks
The platform team builds a staging instance from the restored backup, the same configuration and the same plugins as production. They upgrade staging to the chosen 13.x patch and check that dashboards load, panels render, data sources return results, alert rules evaluate, test notifications reach their contact points, and provisioning and automation calls succeed. Staging is disposable, so a failed check means restoring the staging database from the backup, fixing the cause and repeating the run. Done means a dated test log shows every check passed, with any exceptions documented.
Schedule production with a fresh rollback point
The change owner agrees a maintenance window with the teams that depend on dashboards and alerts, and freezes dashboard and folder edits for that period. The operations owner takes a new backup immediately before the change, because data may have changed since the staging rehearsal. The restore steps, the previous package location and the person authorized to call a rollback are written into the change record. Done means the change record is approved and names the backup and the rollback owner.
Verify folders and dashboards after startup
After production starts on 13, the platform team reviews the startup logs for the folder and dashboard migration to unified storage, which runs on startup. They compare folder and dashboard counts and sample content with the pre-upgrade inventory, then run the alert and automation checks from staging. If counts differ, items are missing or alerts fail, the change owner stops the change and restores the database backup with the 12.x package. Done means a post-upgrade report is signed, and the freeze on edits is lifted.
Why rollback to 12.x depends on restoring the pre-upgrade backup
Rolling back from Grafana 13 to 12.x is a restore, not a downgrade. On startup, Grafana 13 migrates folders and dashboards from the legacy SQL tables into unified storage, and the earlier version cannot read that new layout. The only supported way back is to restore the database backup taken before the upgrade, so that backup is the rollback plan. Before you start the upgrade, confirm that the backup covers the full Grafana database (SQLite grafana.db, or the MySQL or PostgreSQL database you run in production), that you can copy it off the host, and that it is time-stamped with the Grafana version it was taken from. Record the version and the time in the change ticket so that nobody restores a backup from the wrong window.
Verify the backup before you rely on it. A file that exists is not yet a restore point. Restore it into a separate test instance of the same 12.x version, sign in, and check that representative dashboards, folders, data sources and alert rules load as expected. Also confirm that the configuration file, provisioning files and plugin directory you would need for a 12.x restart are stored with the database backup. Avoid the 13.0.0 build for this reason as well: the upgrade guide warns that a migration bug in 13.0.0 could lose or revert dashboards and folders on self-managed instances upgraded from 12.x with Git Sync feature flags enabled. 13.0.0 was withdrawn and the fix shipped in 13.0.1, so start from the latest 13.0 patch and check whether any Git Sync feature flags are on in your instance before you upgrade.
Confirm the restore steps against your own environment. The exact commands, service stops, database tools and ordering depend on your database engine, your deployment method and any high availability setup, so write them down and test them rather than copying generic steps. Ask your database team who owns the backup schedule and restore authority during the window, and agree how long the rollback decision can wait before dashboards are edited on the new version. The Grafana 13.0 upgrade guide is the reference for the rollback warning and should be read alongside your own restore test.
What makes a Grafana 13 upgrade take longer
This table lists the factors that most change how much work a Grafana 12 to 13 upgrade takes, and how to measure each one in your own instance before you plan. Read each row as a question to answer about your environment: the more of these conditions apply, the more plugin checks, script changes, validation and restore testing you should expect. The main takeaway is that plugin age, numeric ID usage and the as-code workflow usually matter more than the dashboard count alone.
| Driver | Effort effect | How to measure |
|---|---|---|
| Number and age of installed plugins | Each plugin needs a React 19 compatibility check and an update before the upgrade. Older or abandoned plugins may need replacing. | List installed plugins with versions and last release dates. Confirm each one's React 19 support with its maintainer. |
| Custom scripts or Terraform calling numeric data source IDs | Numeric-ID data source APIs are disabled by default in 13, so every caller using them needs to move to UID-based calls. | Search automation repositories, cron jobs and Terraform state for data source API paths that contain numeric IDs. |
| Use of Git Sync or provisioning with as-code workflows | Git Sync feature flags in 12.x bring the 13.0.0 migration bug into scope, and provisioned resources need their definitions checked against the new storage layer. | Check feature flags in grafana.ini and environment variables, and list which dashboards and folders are provisioned from files or Git. |
| Database size and backup restore time | A backup is the only supported way back, so the time to take it and to test a restore sets how long the change window must be. | Record current database size for SQLite, MySQL or PostgreSQL, then time a full restore into a non-production copy. |
| High availability topology | Multiple active-active nodes need coordinated upgrades and a check that alerting and Grafana Live still behave as expected during the change. | Count Grafana nodes behind the load balancer, and note any alerting configuration that prevents duplicate notifications. |
| Number of dashboards and folders to validate | Folders and dashboards move from legacy SQL tables to unified storage at startup, so more objects mean more checks on panels, links and permissions. | Export dashboard and folder counts per organization, then pick a sample set that covers each panel and data source type. |
Questions teams ask before upgrading Grafana to 13
How much does a Grafana 12 to 13 upgrade cost?
The cost depends on the scope agreed in writing, and no price is published for this work. The main cost components are the time spent auditing plugins, data sources, dashboards and automation, the staging rehearsal, the upgrade window itself, and the backup and rollback preparation. Ask for a quote that separates one-time work from recurring work, such as a retainer for patches and plugin updates. Items that raise the quote include a large number of custom plugins, Git Sync or provisioning pipelines that must be rebuilt, and high availability clusters that need coordinated node changes. Confirm the exact prerequisites with the Grafana 13.0 upgrade guide before you request a quote, because its checklist defines much of the audit effort.
How long does a Grafana 13 upgrade take?
Duration is set by the size of your estate and by how many items need work before the upgrade can start. No duration is supplied for this work, so treat any estimate as something to confirm in a written scope. The largest drivers are the number of plugins that must be updated for React 19, the number of data sources that use numeric IDs (which are disabled by default in 13), the volume of dashboards and folders that will migrate to unified storage on startup, and whether you run high availability. Plan for a staging rehearsal and a maintenance window, and ask the provider to show which steps depend on each other.
What does the internal team need to provide for the upgrade?
Your team needs to supply access, context and decisions. Expect to provide a current inventory of Grafana servers, plugins, data sources, provisioning files and any automation that calls the API. You also need a database owner who can take and test a backup of the SQLite, MySQL or PostgreSQL database, a named approver for the production window, and someone who knows which dashboards are business critical. Automation owners should be ready to review scripts that use the removed grafana-cli and grafana-server commands or numeric data source IDs. Check the exact list of changes with the Grafana 13.0 upgrade guide.
Can our own team run the Grafana 13 upgrade without outside help?
Yes, an experienced platform team can run the upgrade itself, provided it has the skills and time to do the work. The upgrade guide asks you to move to the latest patch of your current version, update all plugins, and then migrate. Your team will need to handle the changes to command names, the disabled numeric data source APIs, and the unified storage migration. The hard parts are usually plugin compatibility, rebuilding automation, and testing rollback in a realistic environment. A partner can take on the audit, the staging rehearsal and the cutover as a fixed-scope engagement, while your team keeps ownership of dashboards and access. Decide based on capacity and on how much risk your operations group will accept during the window.
Can we roll back a Grafana 13 upgrade without a database backup?
No, a dependable rollback requires a database backup taken before the upgrade. The Grafana 13.0 upgrade guide states that Grafana 13 migrates folders and dashboards from the legacy SQL tables to unified storage on startup, and that returning to an earlier version means restoring the database backup taken before the upgrade. Without that backup, a downgrade can leave dashboards and folders in a state the older version does not read correctly. Back up the database, the configuration and the plugin set, and test a restore in staging before the production window. For the full procedure, read the upgrade guide and plan the rollback steps alongside the backup.
How does the 13.0.0 Git Sync bug affect which Grafana build we choose?
If you run self-managed Grafana with Git Sync feature flags enabled on 12.x, do not upgrade to 13.0.0. The Grafana 13.0 upgrade guide warns that a migration bug in that release could lose or revert dashboards and folders during the move from 12.x. Grafana withdrew 13.0.0, and the fix shipped in 13.0.1, so choose 13.0.1 or a later patch in the 13 line that the guide confirms for your setup. Check the grafana/grafana releases page for the current patch before you pick a target. Also confirm whether your instance has the flags enabled before you plan the change.
Where the Grafana 13.0 upgrade guidance is documented
The primary reference for version-specific steps in this upgrade is the Grafana 13.0 upgrade guide in the Grafana documentation, which covers the changes that need action before or after you move a self-hosted instance from 12.x to 13. Read it in full before scheduling the change, and treat it as the authority for the sequence of steps in this topic. The guide covers the unified storage migration for dashboards and folders, the removed command-line binaries, the disabled numeric-ID data source APIs, and the Git Sync warning for 13.0.0. Print or save the version you read, because the guide is updated over time and your change record should show which text you followed.
Check the Grafana releases page and the release notes for the exact 13.x patch you plan to deploy. The 13.0 guide recommends moving to the latest patch of your current 12.x line before the jump and warns about a migration bug in 13.0.0, which was withdrawn and fixed in 13.0.1. Patch releases can change behavior, so confirm the version number, the fix list and any new known issues on the day you finalize the target build, not only when you first planned the work. Record the build you tested against and the build you deployed.
Confirm with your own team which guide version and release notes govern the change, and keep a dated note of any later patch that touches storage migration or Git Sync. If you use a partner for planning or execution, ask them to name the exact guide revision and patch number in the written scope so the test plan, backup plan and rollback criteria all refer to the same source.
How DeployOpen scopes and delivers a Grafana 12 to 13 upgrade
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes Grafana upgrades. For the 12 to 13 move, the work starts with an inventory of data sources, plugins, storage and automation, then runs through a staged upgrade with a verified backup and written handover.
How we scope
- Inventory of Grafana versions, databases, data sources, plugins and provisioning files in your environment before any change
- Written scope listing which Grafana 13 changes apply to your instance, including plugin and automation remediation
- Agreed deliverables, responsibilities and timelines confirmed in writing before work starts, since most engagements are fixed-scope
How we build
- Update Grafana to the latest 12.x patch and all plugins in a staging copy that mirrors production
- Test a restored database backup against the 13 upgrade, including unified storage migration of dashboards and folders
- Adjust scripts and automation for removed commands and disabled numeric-ID data source APIs, then rehearse rollback
How we hand over
- Written runbook covering the pre-upgrade backup, the upgrade sequence, verification steps and the rollback procedure
- Test results showing dashboards, folders, data sources and alerts checked after the upgrade on staging and production
- Documentation of changed commands, retired API usage and open items for your own team to confirm and own
How we support
- Post-upgrade support window agreed in the written scope, with follow-up on issues found during the first weeks of operation
- Ongoing support, patch upgrades and continuous testing available as a retainer for future Grafana minor and patch releases
- Quote built from the written scope, so your team can compare DeployOpen against doing the upgrade internally
