--- title: "Upgrade to Grafana v12.1 | Grafana documentation" description: "Guide for upgrading to Grafana v12.1" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Upgrade to Grafana v12.1 We recommend that you upgrade Grafana often to stay current with the latest fixes and enhancements. Because Grafana upgrades are backward compatible, the upgrade process is straightforward, and dashboards and graphs will not change. In addition to common tasks you should complete for all versions of Grafana, there might be additional upgrade tasks to complete for a version. > Note > > There might be breaking changes in some releases. We outline all these changes in the [What’s New](/docs/grafana/next/whatsnew/) document. For versions of Grafana prior to v9.2, we published additional information in the [Release Notes](/docs/grafana/next/release-notes/). When available, we list all changes with links to pull requests or issues in the [Changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). > Note > > When possible, we recommend that you test the Grafana upgrade process in a test or development environment. ## Back up Grafana This topic explains how to back up a local Grafana deployment, including configuration, plugin data, and the Grafana database. ### Back up the Grafana configuration file Copy Grafana configuration files that you might have modified in your Grafana deployment to a backup directory. The Grafana configuration files are located in the following directories: - Default configuration: `$WORKING_DIR/defaults.ini` (Don’t change this file) - Custom configuration: `$WORKING_DIR/custom.ini` For more information on where to find configuration files, refer to [Configuration file location](/docs/grafana/next/setup-grafana/configure-grafana/#configuration-file-location). > Note > > If you installed Grafana using the `deb` or `rpm` packages, then your configuration file is located at `/etc/grafana/grafana.ini`. This path is specified in the Grafana `init.d` script using `--config` file parameter. ### Back up plugin data Installing plugins in Grafana creates a folder for each plugin with its associated files and data. Copy all files and folders recursively from this location to your backup repository. The Grafana plugin files are located in the following directories: - Default location for plugins in a binary or source installation: `$WORKING_DIR/data/plugins` - Default location for plugins in a `deb` or `rpm` package: `/var/lib/grafana/plugins`. This path is specified in the Grafana init.d script using `--config` file parameter. ### Back up the Grafana database We recommend that you back up your Grafana database so that you can roll back to a previous version, if required. #### SQLite The default Grafana database is SQLite, which stores its data in a single file on disk. To back up this file, copy it to your backup repository. > Note > > To ensure data integrity, shut down your Grafana service before backing up the SQLite database. The SQLite database file is located in one of the following directories: - Default location for SQLite data in a binary or source installation: `$WORKING_DIR/data/grafana.db` - Default location for SQLite data in a `deb` or `rpm` package: `/var/lib/grafana/grafana.db`. This path is specified in the Grafana init.d script using `--config` file parameter. #### MySQL To back up or restore a MySQL Grafana database, run the following commands: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash backup: > mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql restore: > mysql -u root -p grafana < grafana_backup.sql ``` #### Postgres To back up or restore a Postgres Grafana database, run the following commands: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash backup: > pg_dump grafana > grafana_backup restore: > psql grafana < grafana_backup ``` ## Upgrade Grafana The following sections provide instructions for how to upgrade Grafana based on your installation method. For more information on where to find configuration files, refer to [Configuration file location](/docs/grafana/next/setup-grafana/configure-grafana/#configuration-file-location). ### Debian To upgrade Grafana installed from a Debian package (`.deb`), complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to a file named `/grafana.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. [Download](/grafana/download?platform=linux) the latest version of Grafana. 3. Run the following `dpkg -i` command. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash wget sudo apt-get install -y adduser sudo dpkg -i grafana__amd64.deb ``` ### APT repository To upgrade Grafana installed from the Grafana Labs APT repository, complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to a file named `/grafana.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. Run the following commands: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash sudo apt-get update sudo apt-get upgrade ``` Grafana automatically updates when you run `apt-get upgrade`. ### Binary .tar file To upgrade Grafana installed from the binary `.tar.gz` package, complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to the custom configuration file, `custom.ini` or `grafana.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. [Download](/grafana/download) the binary `.tar.gz` package. 3. Extract the downloaded package and overwrite the existing files. ### RPM or YUM To upgrade Grafana installed using RPM or YUM complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to a file named `/grafana.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. Perform one of the following steps based on your installation. - If you [downloaded an RPM package](/grafana/download) to install Grafana, then complete the steps documented in [Install Grafana on Red Hat, RHEL, or Fedora](/docs/grafana/next/setup-grafana/installation/redhat-rhel-fedora/) or [Install Grafana on SUSE or openSUSE](/docs/grafana/next//setup-grafana/installation/suse-opensuse/) to upgrade Grafana. - If you used the Grafana YUM repository, run the following command: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash sudo yum update grafana ``` - If you installed Grafana on openSUSE or SUSE, run the following command: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash sudo zypper update ``` ### Docker To upgrade Grafana running in a Docker container, complete the following steps: 1. Use Grafana [environment variables](/docs/grafana/next/setup-grafana/configure-grafana/#override-configuration-with-environment-variables) to save your custom configurations; this is the recommended method. Alternatively, you can view your configuration files manually by accessing the deployed container. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. Run a commands similar to the following commands. > Note > > This is an example. The parameters you enter depend on how you configured your Grafana container. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash docker pull grafana/grafana docker stop my-grafana-container docker rm my-grafana-container docker run -d --name=my-grafana-container --restart=always -v /var/lib/grafana:/var/lib/grafana grafana/grafana ``` ### Windows To upgrade Grafana installed on Windows, complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to a file named `/conf/custom.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. [Download](/grafana/download) the Windows binary package. 3. Extract the contents of the package to the location in which you installed Grafana. You can overwrite existing files and folders, when prompted. ### Mac To upgrade Grafana installed on Mac, complete the following steps: 1. In your current installation of Grafana, save your custom configuration changes to the custom configuration file, `custom.ini`. This enables you to upgrade Grafana without the risk of losing your configuration changes. 2. [Download](/grafana/download) the Mac binary package. 3. Extract the contents of the package to the location in which you installed Grafana. You can overwrite existing files and folders, when prompted. ## Update Grafana plugins After you upgrade Grafana, we recommend that you update all plugins because a new version of Grafana can make older plugins stop working properly. Run the following command to update plugins: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash grafana cli plugins update-all ``` ## Technical notes ### 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 `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 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 database. To check your annotation table size, connect to your database and check the table size. For PostgreSQL, run the following query: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql 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: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 database data volume. 2. **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. 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). #### What should I do after upgrading? 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql VACUUM FULL annotation; ``` For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql OPTIMIZE TABLE annotation; ``` For SQLite, run a `VACUUM` operation on the database: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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.