Unified storage for folders and dashboards
Unified storage for folders and dashboards
Warning
Git Sync early adopters: A migration bug in Grafana v13.0.0 might cause dashboards and folders to be lost or reverted when upgrading from Grafana v12.x.x with Git Sync enabled. Upgrading from v13.0.0 to v13.0.1 does not recover lost data, and if you already upgraded, you must restore your database first, then upgrade to v13.0.1.
The bug only affects self-managed instances with Git Sync feature flags (
provisioning,kubernetesClientDashboardsFolders,kubernetesDashboards, andgrafanaAPIServerEnsureKubectlAccess) enabled on Grafana v12.x.x.Grafana v13.0.0 has been removed from distribution and the fix has shipped in Grafana v13.0.1.
If you’re affected, use the following recovery paths:
- If your instance used mixed local and Git Sync content: restore from the database backup you took before upgrading, then upgrade to Grafana v13.0.1.
- If your instance used full-instance Git Sync: upgrade to Grafana v13.0.1 and resync from your Git repository.
- If unsure: restore from your database backup before upgrading to v13.0.1.
Starting with Grafana v13, Grafana automatically migrates folders and dashboards from the legacy SQL database to unified storage during startup and runs data integrity validations to ensure a smooth transition.
After migration completes, the dashboard, dashboard_acl, dashboard_provisioning, dashboard_version, dashboard_tag, library_element_connection, and folder tables are deprecated. These tables will removed in a future release.
This migration is part of a broader initiative to move all Grafana resources to the Grafana App Platform. Unified storage enables features such as Git Sync, allowing you to manage Grafana resources through Git-based workflows, and brings self-managed Grafana closer to feature parity with Grafana Cloud.
For SQLite deployments, configure migration behavior in the [unified_storage] section:
If the migration fails due to SQLite lock contention, Grafana automatically retries using the Parquet buffer. Errors such as database is locked or database table is locked indicate SQLite lock contention during migration. Increase migration_cache_size_kb or enable migration_parquet_buffer to resolve these issues.
Backup and rollback
Always back up your database before upgrading your Grafana instance. If you need to downgrade, use the backup to ensure no data is lost.
If you downgrade to an earlier version of Grafana, any changes made in unified storage after the migration are not reflected in the legacy tables.
The migration runs automatically only once. Grafana records the completed migration in the unifiedstorage_migration_log table and skips it on subsequent startups. If you downgrade and then upgrade again without using a backup, any folders or dashboards created or modified in the legacy tables during the downgrade are not migrated automatically.
Re-running the migration by removing the migration log record replaces all folders and dashboards in unified storage with the data from the legacy tables, discarding any changes made since the original migration. If a backup isn’t available, contact Grafana support for assistance to re-run the migration.
