docs/sources/upgrade-guide/upgrade-v12.0/index.md
{{< docs/shared lookup="upgrade/intro_2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
{{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="<GRAFANA_VERSION>" >}}
Ensure that your data source UIDs follow the correct standard
We've had standard ways to define UIDs for Grafana objects for years (at least since Grafana v5). While all of our internal code complies with this format, we haven't strictly enforced this format in REST APIs and provisioning paths that allow the creation and update of data sources.
In Grafana v11.1, we introduced a warning that is sent to Grafana server logs every time a data source instance is created or updated using an invalid UID format.
In Grafana v11.2, we added a new feature flag called failWrongDSUID that is turned off by default. When enabled, the REST APIs and provisioning reject any requests to create or update data source instances that have an incorrect UID.
In Grafana v12.0, we're turning the feature flag failWrongDSUID on by default.
You can find the exact regex definition in the grafana/grafana repository.
A data source UID can only contain:
a-Z)0-9)-)/api/datasources API. Review the uid fields, comparing them to the correct format, as shown in the docs. The following script can help, but note that it's missing authentication that you have to add yourself:curl http://localhost:3000/api/datasources | jq '.[] | select((.uid | test("^[a-zA-Z0-9\\-_]+$") | not) or (.uid | length > 40)) | {id, uid, name, type}'
Invalid datasource uid error.You'll need to create a new data source with the correct UID and update your dashboards and alert rules to use it.
OR
Update the dashboard's JSON model directly using search and replace.
Navigate to dashboard json model and carefully replace all the instances of the old uid with the newly created uid.
{{< figure src="/media/docs/grafana/screenshot-grafana-11-datasource-uid-enforcement.png" alt="Updating JSON Model of a Dashboard">}}
Open the alert rule you want to adjust and search for the data source that is being used for the query/alert condition. From there, select the new data source from the drop-down list and save the alert rule.
Since Grafana 10.2, the endpoint to check compatible versions when installing a plugin using grafana cli plugins install changed, which led to Grafana dependency version no longer being taken into account. This might have led to some behavior where the CLI would install plugins that are not fully compatible based on the plugins definition of compatibility via grafanaDependency property in the plugin.json file.
We do not recommend installing plugins declared as incompatible. However, if you need to force install a plugin despite it being declared as incompatible, refer to the Installing a plugin from a ZIP guidance.
Plan for increased disk usage when upgrading from Grafana v11.x
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the annotation table. The migration populates the new dashboard_uid column, which causes the database to rewrite the entire table and rebuild its indexes.
Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to:
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large annotation table in your database.
To check your annotation table size, connect to your database and check the table size.
For PostgreSQL, run the following query:
SELECT
pg_size_pretty(pg_relation_size('annotation')) AS table_size,
pg_size_pretty(pg_indexes_size('annotation')) AS indexes_size,
pg_size_pretty(pg_total_relation_size('annotation')) AS total_size;
For MySQL, run the following query:
SELECT
ROUND(data_length / 1024 / 1024, 2) AS table_size_mb,
ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb,
ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = 'annotation';
For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal:
ls -lh <PATH/TO/GRAFANA.DB>
If your total size is several gigabytes or more, you should plan accordingly before upgrading.
Before you upgrade, take the following steps:
Verify available disk space: Ensure you have at least 2-3 times the current annotation table size available as free disk space on your database data volume.
Review your annotation data: Consider whether you need to retain all historical annotations.
Clean up old annotations (optional): If you have annotations you don't need, remove them before upgrading.
Back up your database: Always back up your Grafana database before performing an upgrade. For more information, refer to Back up Grafana.
After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window.
For PostgreSQL, run a VACUUM FULL operation on the annotation table:
VACUUM FULL annotation;
For MySQL, run an OPTIMIZE TABLE operation on the annotation table:
OPTIMIZE TABLE annotation;
For SQLite, run a VACUUM operation on the database:
VACUUM;
These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period.