Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana documentation Upgrade Grafana Upgrade to v8.0

Upgrade to Grafana v8.0

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.

For versions of Grafana prior to v9.2, we published additional information in the Release Notes.

When available, we list all changes with links to pull requests or issues in the Changelog.

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.

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.

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

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

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.

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_install_dir>/grafana.ini.

   This enables you to upgrade Grafana without the risk of losing your configuration changes.

2. Download the latest version of Grafana.

3. Run the following dpkg -i command.

   bash Copy

   wget <debian package url>
   sudo apt-get install -y adduser
   sudo dpkg -i grafana_<version>_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_install_dir>/grafana.ini.

   This enables you to upgrade Grafana without the risk of losing your configuration changes.

2. Run the following commands:

   bash Copy

   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 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_install_dir>/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 to install Grafana, then complete the steps documented in Install Grafana on Red Hat, RHEL, or Fedora or Install Grafana on SUSE or openSUSE to upgrade Grafana.

   • If you used the Grafana YUM repository, run the following command:

     bash Copy

     sudo yum update grafana

   • If you installed Grafana on openSUSE or SUSE, run the following command:

     bash Copy

     sudo zypper update

Docker

To upgrade Grafana running in a Docker container, complete the following steps:

1. Use Grafana 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

   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 <grafana_install_dir>/conf/custom.ini.

   This enables you to upgrade Grafana without the risk of losing your configuration changes.

2. 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 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

grafana cli plugins update-all

Technical notes

This section describes technical changes associated with this release of Grafana.

Plugins

Grafana now requires all plugins to be signed. If a plugin is not signed Grafana will not load/start it. This is an additional security measure to make sure plugin files and binaries haven’t been tampered with. All Grafana Labs authored plugins, including Enterprise plugins, are now signed. It’s possible to allow unsigned plugins using a configuration setting, but is something we strongly advise against doing. For more information about this setting, refer to allow loading unsigned plugins.

Grafana Live

Grafana now maintains persistent WebSocket connections for real-time messaging needs.

When WebSocket connection is established, Grafana checks the request Origin header due to security reasons (for example, to prevent hijacking of WebSocket connection). If you have a properly defined public URL (root_url server option) then the origin check should successfully pass for WebSocket requests originating from public URL pages. In case of an unsuccessful origin check, Grafana returns a 403 error. It’s also possible to add a list of additional origin patterns for the origin check.

To handle many concurrent WebSocket connections you may need to tune your OS settings or infrastructure. Grafana Live is enabled by default and supports 100 concurrent WebSocket connections max to avoid possible problems with the file descriptor OS limit. As soon as your setup meets the requirements to scale the number of persistent connections this limit can be increased. You also have an option to disable Grafana Live.

Refer to Grafana Live configuration documentation for more information.

Postgres, MySQL, Microsoft SQL Server data sources

Grafana v8.0 changes the underlying data structure to data frames for the Postgres, MySQL, Microsoft SQL Server data sources. As a result, a Time series query result gets returned in a wide format. To make the visualizations work as they did before, you might have to do some manual migrations.

For any existing panels/visualizations using a Time series query, where the time column is only needed for filtering the time range, for example, using the bar gauge or pie chart panel, we recommend that you use a Table query instead and exclude the time column as a field in the response. Refer to this issue comment for detailed instructions and workarounds.

Prefix added to series names

When you have a query where there’s a time value and a numeric value selected together with a string value that’s not named metric, the graph panel renders series names as value <hostname> rather than just <hostname> which was the case before Grafana 8.

sql Copy

SELECT
  $__timeGroup("createdAt",'10m'),
  avg(value) as "value",
  hostname
FROM grafana_metric
WHERE $__timeFilter("createdAt")
GROUP BY time, hostname
ORDER BY time

There are two possible workarounds to resolve this problem:

1. In Grafana v8.0.3, use an alias of the string column selected as metric. for example, hostname as metric.
2. Use the Standard field definitions’ display name to format the alias. For the preceding example query, you would use ${__field.labels.hostname} option.

For more information, refer to the our relational databases documentation of Postgres, MySQL, Microsoft SQL Server.