From 4f6ae738c94fadacb6595b0510e85c1c19642a1c Mon Sep 17 00:00:00 2001 From: Jacob Valdez Date: Wed, 17 Dec 2025 16:29:16 -0600 Subject: [PATCH] [release-12.2.4] docs: update the technical note for annotation bloat (#115521) --- .../upgrade-guide/upgrade-v12.0/index.md | 56 +++++++++++++++---- .../upgrade-guide/upgrade-v12.1/index.md | 56 +++++++++++++++---- .../upgrade-guide/upgrade-v12.2/index.md | 56 +++++++++++++++---- 3 files changed, 135 insertions(+), 33 deletions(-) diff --git a/docs/sources/upgrade-guide/upgrade-v12.0/index.md b/docs/sources/upgrade-guide/upgrade-v12.0/index.md index feb1061dceb..b166cc2c022 100644 --- a/docs/sources/upgrade-guide/upgrade-v12.0/index.md +++ b/docs/sources/upgrade-guide/upgrade-v12.0/index.md @@ -81,24 +81,26 @@ Since Grafana 10.2, the endpoint to check compatible versions when installing a 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](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-plugin-from-a-zip-file) guidance. -### PostgreSQL annotation table migration +### Annotation table migration **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 PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes. +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: -- Rapid disk consumption on the PostgreSQL data volume +- Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? -You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database. +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 PostgreSQL database and run the following query: +To check your annotation table size, connect to your database and check the table size. + +For PostgreSQL, run the following query: ```sql SELECT @@ -107,26 +109,58 @@ SELECT pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` +For MySQL, run the following query: + +```sql +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: + +```bash +ls -lh +``` + If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: -1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume. +1. **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. -2. **Review your annotation data**: Consider whether you need to retain all historical annotations. +1. **Review your annotation data**: Consider whether you need to retain all historical annotations. -3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. +1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. -4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). +1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? -After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window: +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: ```sql VACUUM FULL annotation; ``` -This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period. +For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: + +```sql +OPTIMIZE TABLE annotation; +``` + +For SQLite, run a `VACUUM` operation on the database: + +```sql +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. diff --git a/docs/sources/upgrade-guide/upgrade-v12.1/index.md b/docs/sources/upgrade-guide/upgrade-v12.1/index.md index 7dbcb11ece9..9a96c0cbc0a 100644 --- a/docs/sources/upgrade-guide/upgrade-v12.1/index.md +++ b/docs/sources/upgrade-guide/upgrade-v12.1/index.md @@ -21,24 +21,26 @@ weight: 499 ## Technical notes -### PostgreSQL annotation table migration +### Annotation table migration **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 PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes. +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: -- Rapid disk consumption on the PostgreSQL data volume +- Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? -You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database. +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 PostgreSQL database and run the following query: +To check your annotation table size, connect to your database and check the table size. + +For PostgreSQL, run the following query: ```sql SELECT @@ -47,26 +49,58 @@ SELECT pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` +For MySQL, run the following query: + +```sql +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: + +```bash +ls -lh +``` + If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: -1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume. +1. **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. -2. **Review your annotation data**: Consider whether you need to retain all historical annotations. +1. **Review your annotation data**: Consider whether you need to retain all historical annotations. -3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. +1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. -4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). +1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? -After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window: +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: ```sql VACUUM FULL annotation; ``` -This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period. +For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: + +```sql +OPTIMIZE TABLE annotation; +``` + +For SQLite, run a `VACUUM` operation on the database: + +```sql +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. diff --git a/docs/sources/upgrade-guide/upgrade-v12.2/index.md b/docs/sources/upgrade-guide/upgrade-v12.2/index.md index 1e900d65793..221ae3f152c 100644 --- a/docs/sources/upgrade-guide/upgrade-v12.2/index.md +++ b/docs/sources/upgrade-guide/upgrade-v12.2/index.md @@ -21,24 +21,26 @@ weight: 498 ## Technical notes -### PostgreSQL annotation table migration +### Annotation table migration **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 PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes. +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: -- Rapid disk consumption on the PostgreSQL data volume +- Rapid disk consumption on the database data volume - Database migration failures (for example, "could not extend file: No space left on device") - Grafana startup failures - Extended downtime during the upgrade process #### How do I know if I'm affected? -You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database. +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 PostgreSQL database and run the following query: +To check your annotation table size, connect to your database and check the table size. + +For PostgreSQL, run the following query: ```sql SELECT @@ -47,26 +49,58 @@ SELECT pg_size_pretty(pg_total_relation_size('annotation')) AS total_size; ``` +For MySQL, run the following query: + +```sql +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: + +```bash +ls -lh +``` + If your total size is several gigabytes or more, you should plan accordingly before upgrading. #### What should I do before upgrading? Before you upgrade, take the following steps: -1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume. +1. **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. -2. **Review your annotation data**: Consider whether you need to retain all historical annotations. +1. **Review your annotation data**: Consider whether you need to retain all historical annotations. -3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. +1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading. -4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). +1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana). #### What should I do after upgrading? -After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window: +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: ```sql VACUUM FULL annotation; ``` -This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period. +For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: + +```sql +OPTIMIZE TABLE annotation; +``` + +For SQLite, run a `VACUUM` operation on the database: + +```sql +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.