MySQL data source on Grafana Labs

Configure the MySQL data source

Fri, 03 Apr 2026 19:43:06 +0000

Configure the MySQL data source

This document provides instructions for configuring the MySQL data source and explains available configuration options. For general information on managing data sources refer to Data source management.

Before you begin

Before configuring the MySQL data source, ensure you have the following:

Grafana permissions: You must have the Organization administrator role to configure data sources. Organization administrators can also configure the data source via YAML with the Grafana provisioning system.
A running MySQL instance: MySQL 5.7 or newer, MariaDB 10.2 or newer, or a compatible MySQL-based database such as Percona Server.
Network access: Grafana must be able to reach your MySQL server. The default port is 3306.
Authentication credentials: A MySQL user with at least SELECT permissions on the databases and tables you want to query.
Security certificates: If using encrypted connections, gather any necessary TLS/SSL certificates.

Note
Grafana ships with a built-in MySQL data source plugin. No additional installation is required.

Tip
Grafana Cloud users: If your MySQL server is in a private network, you can configure Private data source connect to establish connectivity.

Database user permissions

When adding a data source, ensure the database user you specify has only SELECT permissions on the relevant database and tables. Grafana doesn’t validate the safety of queries, which means they can include potentially harmful SQL statements, such as USE otherdb; or DROP TABLE user;, which could get executed.

To minimize this risk, Grafana strongly recommends creating a dedicated MySQL user with restricted permissions:

CREATE USER 'grafanaReader' IDENTIFIED BY 'password';
GRANT SELECT ON mydatabase.mytable TO 'grafanaReader';

Use wildcards (*) in place of a database or table if you want to grant access to more databases and tables.

Add the MySQL data source

To add the MySQL data source complete the following steps:

Click Connections in the left-side menu.
Click Add new connection and type MySQL in the search bar.
Select the MySQL data source option.
Click Add new data source in the upper right.

You are taken to the Settings tab where you will configure the data source.

MySQL configuration options

Following is a list of MySQL configuration options:

Name - Sets the name you use to refer to the data source in panels and queries. Examples: mysql-assets-1, mysqldb1.
Default - Toggle to make this specific MySQL data source the default pre-selected data source in panels and visualizations.

Connection:

Host URL - Enter the IP address/hostname and optional port of your MySQL instance. If the port is omitted the default 3306 port will be used.
Database - Enter the name of your MySQL database.

Authentication:

Username- Enter the username used to connect to your MySQL database.
Password - Enter the password used to connect to the MySQL database.
Use TLS Client Auth - Toggle to enable TLS authentication using the client certificate specified in the secure JSON configuration. Refer to Using TLS Connections and Configuring MySQL to Use Encrypted Connections for more information regarding TLS and configuring encrypted connections in MySQL. Provide the client certificate under TLS/SSL Client Certificate. Provide the key under TLS/SSL Client Key.
With CA Cert - Toggle to authenticate using a CA certificate. Required for verifying self-signed TLS Certs. Follow the instructions of your CA (Certificate Authority) to download the certificate file. Provide the root certificate under TLS/SSL Root Certificate if TLS/SSL mode requires it.
Skip TLS Verification - Toggle to skip verification of the MySQL server’s TLS certificate chain and host name.
Allow Cleartext Passwords - Toggle to allow the use of the cleartext client-side plugin when required by a specific type of account, such as one defined with the PAM authentication plugin. Note that transmitting passwords in plain text can pose a security risk in certain configurations. To prevent password-related issues, it is recommended that clients connect to a MySQL server using a secure method that protects the password. Options include TLS/SSL, IPsec, or a private network.

Additional settings

The following are additional MySQL settings.

MySQL options:

Session Timezone - Specifies the timezone used in the database session, such as Europe/Berlin or +02:00. Required if the timezone of the database (or the host of the database) is set to something other than UTC. Set this to +00:00 so Grafana can handle times properly. Set the value used in the session with SET time_zone='...'. If you leave this field empty, the timezone will not be updated. For more information, refer to MySQL Server Time Zone Support.
Min time interval - Defines a lower limit for the $__interval and $__interval_ms variables. Grafana recommends aligning this setting with the data write frequency. For example, set it to 1m if your data is written every minute. Refer to Min time interval for format examples.

Connection limits:

Max open - The maximum number of open connections to the database, default 100.
Max idle - The maximum number of connections in the idle connection pool, default 100.
Auto (max idle) - Toggle to set the maximum number of idle connections to the number of maximum open connections. The default is true.
Max lifetime - The maximum amount of time in seconds a connection may be reused. This should always be lower than configured wait_timeout in MySQL. The default is 14400, or 4 hours.

Private data source connect:

Private data source connect - Only for Grafana Cloud users. Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to Private data source connect (PDC).

Click Manage private data source connect to be taken to your PDC connection page, where you’ll find your PDC configuration details.

Once you have added your MySQL connection settings, click Save & test to test and save the data source connection.

Min time interval

The Min time interval setting defines a lower limit for the $__interval and $__interval_ms variables.

This value must be formatted as a number followed by a valid time identifier:

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

You can override this setting in a dashboard panel under its data source options.

Provision the data source

You can define and configure the data source in YAML files as part of Grafana’s provisioning system. For more information about provisioning, and available configuration options, refer to Provision Grafana.

MySQL provisioning examples

Basic provisioning:

apiVersion: 1

datasources:
  - name: MySQL
    type: mysql
    url: localhost:3306
    user: grafana
    jsonData:
      database: grafana
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
    secureJsonData:
      password: ${GRAFANA_MYSQL_PASSWORD}

Using TLS verification:

apiVersion: 1

datasources:
  - name: MySQL
    type: mysql
    url: localhost:3306
    user: grafana
    jsonData:
      tlsAuth: true
      database: grafana
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
    secureJsonData:
      password: ${GRAFANA_MYSQL_PASSWORD}
      tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
      tlsCACert: ${GRAFANA_TLS_CA_CERT}

Use TLS and skip certificate verification:

apiVersion: 1

datasources:
  - name: MySQL
    type: mysql
    url: localhost:3306
    user: grafana
    jsonData:
      tlsAuth: true
      tlsSkipVerify: true
      database: grafana
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
    secureJsonData:
      password: ${GRAFANA_MYSQL_PASSWORD}
      tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
      tlsCACert: ${GRAFANA_TLS_CA_CERT}

Configure with Terraform

You can configure the MySQL data source using Terraform with the Grafana Terraform provider.

For more information about provisioning resources with Terraform, refer to the Grafana as code using Terraform documentation.

Terraform example

The following example creates a basic MySQL data source:

resource "grafana_data_source" "mysql" {
  name = "MySQL"
  type = "mysql"
  url  = "localhost:3306"
  user = "grafana"

  json_data_encoded = jsonencode({
    database         = "grafana"
    maxOpenConns     = 100
    maxIdleConns     = 100
    maxIdleConnsAuto = true
    connMaxLifetime  = 14400
  })

  secure_json_data_encoded = jsonencode({
    password = "password"
  })
}

For all available configuration options, refer to the Grafana provider data source resource documentation.

Next steps

After configuring your MySQL data source, you can:

Write queries using the query editor to explore and visualize your data.
Use template variables to create dynamic, reusable dashboards.
Add annotations to overlay MySQL events on your graphs.
Set up alerting to create alert rules based on your MySQL data.
Troubleshoot issues if you encounter problems with your data source.

MySQL query editor

Fri, 03 Apr 2026 19:43:06 +0000

MySQL query editor

Grafana’s query editors are unique for each data source. For general information on Grafana query editors, refer to Query editors. For general information on querying data sources in Grafana, refer to Query and transform data.

The MySQL query editor is located on the Explore page. You can also access the MySQL query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select Edit.

Note
If a default database is configured in the Data Source Configuration page, or via a provisioning configuration file, users will be restricted to querying only that pre-configured database.

MySQL query editor components

The MySQL query editor has two modes: Builder and Code.

Builder mode helps you build a query using a visual interface. Code mode allows for advanced querying and offers support for complex SQL query writing.

Note
If your table or database name contains a reserved word or a prohibited character the editor will put quotes around the name. For example, the name table-name will be quoted with backticks - `table-name`.

MySQL Builder mode

The following components will help you build a MySQL query:

Format - Select a format response from the drop-down for the MySQL query. The default is Table. If you use the Time series format option, one of the columns must be time.
Dataset - Select a database to query from the drop-down.
- Table - Select a table from the drop-down. Tables correspond to the chosen database.
- Data operations - Optional Select an aggregation from the drop-down. You can add multiple data operations by clicking the + sign. Click the X to remove a data operation. Click the garbage can icon to remove the entire column.
- Column - Select a column on which to run the aggregation.
- Alias - Optional Add an alias from the drop-down. You can also add your own alias by typing it in the box and clicking Enter. Remove an alias by clicking the X.
Filter - Toggle to add filters.
- Filter by column value - Optional If you toggle Filter you can add a column to filter by from the drop-down. To filter on more columns, click the + sign to the right of the condition drop-down. You can choose a variety of operators from the drop-down next to the condition. When multiple filters are added you can add an AND operator to display all true conditions or an OR operator to display any true conditions. Use the second drop-down to choose a filter. To remove a filter, click the X button next to that filter’s drop-down. After selecting a date type column, you can choose Macros from the operators list and select timeFilter which will add the $\_\_timeFilter macro to the query with the selected date column.
Group - Toggle to add Group by column.
- Group by column - Select a column to filter by from the drop-down. Click the + sign to filter by multiple columns. Click the X to remove a filter.
Order - Toggle to add an ORDER BY statement.
- Order by - Select a column to order by from the drop-down. Select ascending (ASC) or descending (DESC) order.
- Limit - You can add an optional limit on the number of retrieved results. Default is 50.
Preview - Toggle for a preview of the SQL query generated by the query builder. Preview is toggled on by default.

MySQL Code mode

To create advanced queries, switch to Code mode by clicking Code in the upper right of the editor window. Code mode supports the auto-completion of tables, columns, SQL keywords, standard SQL functions, Grafana template variables, and Grafana macros. Columns cannot be completed before a table has been specified.

Select Table or Time Series as the format. Click the {} in the bottom right to format the query. Click the downward caret to expand the Code mode editor. CTRL/CMD + Return serves as a keyboard shortcut to execute the query.

Warning
Changes made to a query in Code mode will not transfer to Builder mode and will be discarded. You will be prompted to copy your code to the clipboard to save any changes.

Macros

You can add macros to your queries to simplify the syntax and enable dynamic elements, such as date range filters.

Macro example	Description
`$__time(dateColumn)`	Replaces the value with an expression to convert to a UNIX timestamp and renames the column to `time_sec`. It also helps to recognize the `time` column, as required in Time Series format. Example: UNIX_TIMESTAMP(dateColumn) AS time_sec.
`$__timeEpoch(dateColumn)`	Replaces the value with an expression to convert to a UNIX Epoch timestamp and renames the column to `time_sec`. Example: UNIX_TIMESTAMP(dateColumn) AS time_sec.
`$__timeFilter(dateColumn)`	Applies a time range filter using the specified column name and fetches only the data that falls within that range. Example: dateColumn BETWEEN FROM_UNIXTIME(1494410783) AND FROM_UNIXTIME(1494410983)
`$__timeFrom()`	Replaces the value with the start of the currently active time selection. Example: FROM_UNIXTIME(1494410783)
`$__timeTo()`	Replaces the value with the end of the currently active time selection. Example: FROM_UNIXTIME(1494410983)
`$__timeGroup(dateColumn,'5m')`	Replaces the value with an expression suitable for use in a GROUP BY clause and creates the bucket timestamps at a fixed interval. Example: cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)300 as signed),*
`$__timeGroup(dateColumn,'5m', 0)`	Same as the `$__timeGroup(dateColumn,'5m')` macro, but includes a fill parameter to ensure missing points in the series are added by Grafana, using 0 as the default value. This applies only to time series queries.
`$__timeGroup(dateColumn,'5m', NULL)`	Same as the `$__timeGroup(dateColumn,'5m', 0)` but NULL is used as the value for missing points. This applies only to time series queries.
`$__timeGroup(dateColumn,'5m', previous)`	Same as the `$__timeGroup(dateColumn,'5m', previous)` macro, but uses the previous value in the series as the fill value. If no previous value exists,`NULL` will be used. This applies only to time series queries.
`$__timeGroupAlias(dateColumn,'5m')`	Replaces the value identical to $__timeGroup but with an added column alias.
`$__unixEpochFilter(dateColumn)`	Replaces the value by a time range filter using the specified column name with times represented as a UNIX timestamp. Example: dateColumn > 1494410783 AND dateColumn < 1494497183
`$__unixEpochFrom()`	Replaces the value with the start of the currently active time selection as a UNIX timestamp. Example: 1494410783
`$__unixEpochTo()`	Replaces the value with the end of the currently active time selection as UNIX timestamp. Example: 1494497183
`$__unixEpochNanoFilter(dateColumn)`	Replaces the value with a time range filter using the specified column name with time represented as a nanosecond timestamp. Example: dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872
`$__unixEpochNanoFrom()`	Replaces the value with the start of the currently active time selection as nanosecond timestamp. Example: 1494410783152415214
`$__unixEpochNanoTo()`	Replaces the value with the end of the currently active time selection as nanosecond timestamp. Example: 1494497183142514872
`$__unixEpochGroup(dateColumn,'5m', [fillmode])`	Same as $__timeGroup but for times stored as Unix timestamp. Note that `fillMode` only works with time series queries.
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`	Same as $__timeGroup but also adds a column alias. Note that `fillMode` only works with time series queries.

Table SQL queries

If the Format option is set to Table, you can execute virtually any type of SQL query. The Table panel will automatically display the resulting columns and rows from your query.

You can change or customize the name of a Table panel column by using the SQL keyword AS syntax.

SELECT
  title as 'Title',
  user.login as 'Created By' ,
  dashboard.created as 'Created On'
 FROM dashboard
INNER JOIN user on user.id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)

Table panel results:

Time series queries

Set the Format option to Time series to create and run time series queries.

Note
To run a time series query you must include a column named time that returns either a SQL datetime value or a numeric datatype representing the UNIX epoch time in seconds. Additionally, the query results must be sorted by the time column for proper visualization in panels.

The examples in this section refer to the data in the following table:

+---------------------+--------------+---------------------+----------+
| time_date_time      | value_double | CreatedAt           | hostname |
+---------------------+--------------+---------------------+----------+
| 2025-01-02 03:05:00 | 3.0          | 2025-01-02 03:05:00 | 10.0.1.1 |
| 2025-01-02 03:06:00 | 4.0          | 2025-01-02 03:06:00 | 10.0.1.2 |
| 2025-01-02 03:10:00 | 6.0          | 2025-01-02 03:10:00 | 10.0.1.1 |
| 2025-01-02 03:11:00 | 7.0          | 2025-01-02 03:11:00 | 10.0.1.2 |
| 2025-01-02 03:20:00 | 5.0          | 2025-01-02 03:20:00 | 10.0.1.2 |
+---------------------+--------------+---------------------+----------+

Note
For backward compatibility, an exception to the aforementioned rule applies to queries returning three columns, including a string column named metric. Instead of converting the metric column into field labels, it is used as the field name, and the series name is set to the value of the metric column. Refer to the following example with a metric column.

Example with $__time(dateColumn) Macro:

SELECT
  $__time(time_date_time),
  value_double
FROM my_data
ORDER BY time_date_time

Table panel result:

In the following example, the result includes two columns, Time and value_double, which represent the data associated with fixed timestamps. This query does not apply a time range filter and returns all rows from the table.

Example with $__timeFilter(dateColumn) Macro:

SELECT
  $__time(time_date_time),
  value_double
FROM my_data
WHERE $__timeFilter(time_date_time)
ORDER BY time_date_time

Table panel result:

This example returns the same result as the previous one, but adds support for filtering data using the Grafana time picker.

Example with $__timeGroup(dateColumn,'5m') Macro:

SELECT
  $__timeGroup(time_date_time, '5m') AS time,
  sum(value_double) AS sum_value
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time

Table panel result:

Given the result in the following example, the data is grouped and aggregated within buckets with timestamps of fixed interval i.e. 5 mins. To customize the default series name formatting (optional), refer to Standard options definitions.

Example with $__timeGroupAlias(dateColumn,'5m') Macro:

SELECT
  $__timeGroupAlias(time_date_time,'5m'),
  min(value_double),
  'min' as metric
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time

Table panel result:

The following result is similar to the result of the $__timeGroup(dateColumn,'5m') macro, except it uses a built-in alias for the time column. To customize the default series name formatting (optional), refer to Standard options definitions.

Example with $__timeGroupAlias Macro to convert null values to zero instead:

SELECT
  $__timeGroupAlias(createdAt,'5m',0),
  sum(value_double) as value,
  hostname
FROM my_data
WHERE
  $__timeFilter(createdAt)
GROUP BY time, hostname
ORDER BY time

Table panel result:

Given the result in the following example, null values within bucket timestamps are replaced by zero and also add the Time column alias by default. To customize the default series name formatting (optional), refer to Standard options definitions to display the value of ${__field.labels.hostname}.

Example with multiple columns for $__timeGroupAlias(dateColumn,'5m') Macro:

SELECT
  $__timeGroupAlias(time_date_time,'5m'),
  min(value_double) as min_value,
  max(value_double) as max_value
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time

Table panel result:

The query returns multiple columns representing minimum and maximum values within the defined range.

Template variables

Instead of hard-coding values like server, application, or sensor names in your metric queries, you can use variables. Variables appear as drop-down select boxes at the top of the dashboard, making it easy to change the data displayed in your dashboard.

For detailed information on using template variables with MySQL, refer to MySQL template variables.

Annotations

Annotations allow you to overlay event information on your graphs, helping you correlate events with metrics. You can write SQL queries that return event data to display as annotations on your dashboards.

For detailed information on creating annotations with MySQL, refer to MySQL annotations.

Alerting

You can use time series queries to create Grafana-managed alert rules. Table formatted queries are not supported in alert rule conditions.

For detailed information on creating alerts with MySQL, refer to MySQL alerting.

MySQL template variables

Fri, 03 Apr 2026 19:43:06 +0000

MySQL template variables

Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana displays these variables in drop-down select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.

For an introduction to templating and template variables, refer to Templating and Add and manage variables.

Query variable

A query variable in Grafana dynamically retrieves values from your data source using a query. With a query variable, you can write a SQL query that returns values such as measurement names, key names, or key values that are shown in a drop-down select box.

For example, the following query returns all values from the hostname column:

SELECT hostname FROM my_host

A query can return multiple columns, and Grafana automatically generates a list using the values from those columns. For example, the following query returns values from both the hostname and hostname2 columns, which are included in the variable’s drop-down list.

SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city

To use time range dependent macros like $__timeFilter(column) in your query, you must set the template variable’s refresh mode to On Time Range Change.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

Key/value variables

You can create a key/value variable using a query that returns two columns named __text and __value.

The __text column defines the label shown in the drop-down.
The __value column defines the value passed to panel queries.

This is useful when you want to display a user-friendly label (like a hostname) but use a different underlying value (like an ID).

Note that the values in the __text column should be unique. If there are duplicates, Grafana uses only the first matching entry.

SELECT hostname AS __text, id AS __value FROM my_host

Nested variables

You can create nested variables, where one variable depends on the value of another. For example, if you have a variable named region, you can configure a hosts variable to only show hosts from the selected region. If region is a multi-value variable, use the IN operator instead of = to match against multiple selected values.

SELECT hostname FROM my_host WHERE region IN($region)

Filter results with `__searchFilter`

Using __searchFilter in the query field allows the query results to be filtered based on the user’s input in the drop-down selection box. If you don’t enter anything, the default value for __searchFilter is %.

Note that you must enclose the __searchFilter expression in quotes as Grafana doesn’t add them automatically.

The following example demonstrates how to use __searchFilter in the query field to enable real-time searching for hostname as the user types in the drop-down selection box.

SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter'

Use variables in queries

Grafana automatically quotes template variable values only when the template variable is a multi-value.

When using a multi-value variable, use the IN comparison operator instead of = to match against multiple values.

Grafana supports two syntaxes for using variables in queries:

$<varname> syntax

Example with a template variable named hostname:

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC

[[varname]] syntax

Example with a template variable named hostname:

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC

Disable quoting for multi-value variables

By default, Grafana formats multi-value variables as a quoted, comma-separated string. For example, if server01 and server02 are selected, the result will be 'server01', 'server02'. To disable quoting, use the csv formatting option for variables:

${servers:csv}

This outputs the values as an unquoted comma-separated list.

Refer to Advanced variable format options for additional information.

MySQL annotations

Fri, 03 Apr 2026 19:43:06 +0000

MySQL annotations

Annotations overlay event data on your dashboard graphs, helping you correlate events with metrics. You can use MySQL as a data source for annotations to display events such as deployments, alerts, or other significant occurrences on your visualizations.

For general information about annotations, refer to Annotate visualizations.

Before you begin

Before creating MySQL annotations, ensure you have:

A MySQL data source configured in Grafana.
Tables containing event data with timestamp fields.
Read access to the tables containing your events.

Create an annotation query

To add a MySQL annotation to your dashboard:

Navigate to your dashboard and click Dashboard settings (gear icon).
Select Annotations in the left menu.
Click Add annotation query.
Enter a Name for the annotation.
Select your MySQL data source from the Data source drop-down.
Write a SQL query that returns the required columns.
Click Save dashboard.

Query columns

Your annotation query must return a time column and can optionally include timeend, text, and tags columns.

Column	Required	Description
`time`	Yes	The timestamp for the annotation. Can be a SQL datetime or UNIX epoch value.
`timeend`	No	The end timestamp for range annotations. Creates a shaded region instead of a vertical line.
`text`	No	The annotation description displayed when you hover over the annotation.
`tags`	No	Tags for the annotation as a comma-separated string. Helps categorize and filter annotations.

Example queries

The following examples show common annotation query patterns.

Basic annotation with epoch time

Display events using UNIX epoch timestamps:

SELECT
  epoch_time as time,
  description as text,
  CONCAT(tag1, ',', tag2) as tags
FROM events
WHERE $__unixEpochFilter(epoch_time)

Annotation with a single tag

Display events with a single tag value:

SELECT
  epoch_time as time,
  message as text,
  category as tags
FROM event_log
WHERE $__unixEpochFilter(epoch_time)

Range annotation with start and end time

Display events with duration as shaded regions:

SELECT
  start_time as time,
  end_time as timeend,
  description as text,
  CONCAT(type, ',', severity) as tags
FROM incidents
WHERE $__unixEpochFilter(start_time)

Annotation with native SQL datetime

Display events using native MySQL datetime columns:

SELECT
  event_date as time,
  message as text,
  CONCAT(category, ',', priority) as tags
FROM system_events
WHERE $__timeFilter(event_date)

Deployment annotations

Display deployment events:

SELECT
  deployed_at as time,
  CONCAT('Deployed ', version, ' to ', environment) as text,
  environment as tags
FROM deployments
WHERE $__timeFilter(deployed_at)

Maintenance window annotations

Display maintenance windows as range annotations:

SELECT
  start_time as time,
  end_time as timeend,
  CONCAT('Maintenance: ', description) as text,
  'maintenance' as tags
FROM maintenance_windows
WHERE $__timeFilter(start_time)

Macros

Use these macros in your annotation queries to filter by the dashboard time range:

Macro	Description
`$__timeFilter(column)`	Filters by time range using a native SQL datetime column.
`$__unixEpochFilter(column)`	Filters by time range using a column with UNIX epoch timestamps.

Best practices

Follow these best practices when creating MySQL annotations:

Use time filters: Always include $__timeFilter() or $__unixEpochFilter() to limit results to the dashboard time range.
Keep queries efficient: Add indexes on time columns and filter columns to improve query performance.
Use meaningful text: Include descriptive information in the text column to make annotations useful.
Organize with tags: Use consistent tag values to categorize annotations and enable filtering.
Test queries first: Verify your query returns expected results in Explore before adding it as an annotation.

MySQL alerting

Fri, 03 Apr 2026 19:43:06 +0000

MySQL alerting

You can use Grafana Alerting with MySQL to create alerts based on your MySQL data. This allows you to monitor metrics, detect anomalies, and receive notifications when specific conditions are met.

For general information about Grafana Alerting, refer to Grafana Alerting.

Before you begin

Before creating alerts with MySQL, ensure you have:

A MySQL data source configured in Grafana.
Appropriate permissions to create alert rules.
Understanding of the metrics you want to monitor.

Supported query types

MySQL alerting works with time series queries that return numeric data over time. Table formatted queries are not supported in alert rule conditions.

To create a valid alert query:

Include a time column that returns a SQL datetime or UNIX epoch timestamp
Return numeric values for the metrics you want to alert on
Sort results by the time column

For more information on writing time series queries, refer to MySQL query editor.

Query format requirements

Query format	Alerting support	Notes
Time series	Yes	Required for alerting
Table	No	Convert to time series format for alerts

Create an alert rule

To create an alert rule using MySQL:

Navigate to Alerting > Alert rules.
Click New alert rule.
Enter a name for the alert rule.
Select your MySQL data source.
Build your query using the query editor:
- Set the Format to Time series
- Include a time column using the $__time() or $__timeGroup() macro
- Add numeric columns for the values to monitor
- Use $__timeFilter() to filter data by the dashboard time range
Configure the alert condition (for example, when the average is above a threshold).
Set the evaluation interval and pending period.
Configure notifications and labels.
Click Save rule.

For detailed instructions, refer to Create a Grafana-managed alert rule.

Example alert queries

The following examples show common alerting scenarios with MySQL.

Alert on high error count

Monitor the number of errors over time:

SELECT
  $__timeGroup(created_at, '1m') AS time,
  COUNT(*) AS error_count
FROM error_logs
WHERE $__timeFilter(created_at)
  AND level = 'error'
GROUP BY time
ORDER BY time

Condition: When error_count is above 100.

Alert on average response time

Monitor API response times:

SELECT
  $__timeGroup(request_time, '5m') AS time,
  AVG(response_time_ms) AS avg_response_time
FROM api_requests
WHERE $__timeFilter(request_time)
GROUP BY time
ORDER BY time

Condition: When avg_response_time is above 500 (milliseconds).

Alert on low order volume

Detect drops in order activity:

SELECT
  $__timeGroup(order_date, '1h') AS time,
  COUNT(*) AS order_count
FROM orders
WHERE $__timeFilter(order_date)
GROUP BY time
ORDER BY time

Condition: When order_count is below 10.

Alert on disk usage percentage

Monitor database storage metrics:

SELECT
  $__timeGroup(recorded_at, '5m') AS time,
  AVG(disk_used_percent) AS disk_usage
FROM system_metrics
WHERE $__timeFilter(recorded_at)
  AND metric_type = 'disk'
GROUP BY time
ORDER BY time

Condition: When disk_usage is above 85.

Limitations

When using MySQL with Grafana Alerting, be aware of the following limitations:

Template variables not supported

Alert queries cannot contain template variables. Grafana evaluates alert rules on the backend without dashboard context, so variables like $hostname or $environment won’t be resolved.

If your dashboard query uses template variables, create a separate query for alerting with hard coded values.

Table format not supported

Queries using the Table format cannot be used for alerting. Set the query format to Time series and ensure your query returns a time column.

Query timeout

Complex queries with large datasets may timeout during alert evaluation. Optimize queries for alerting by:

Adding appropriate WHERE clauses to limit data
Using indexes on time and filter columns
Reducing the time range evaluated

Best practices

Follow these best practices when creating MySQL alerts:

Use time series format: Always set the query format to Time series for alert queries.
Include time filters: Use the $__timeFilter() macro to limit data to the evaluation window.
Optimize queries: Add indexes on columns used in WHERE clauses and GROUP BY.
Test queries first: Verify your query returns expected results in Explore before creating an alert.
Set realistic thresholds: Base alert thresholds on historical data patterns.
Use meaningful names: Give alert rules descriptive names that indicate what they monitor.

Troubleshoot MySQL data source issues

Fri, 03 Apr 2026 19:43:06 +0000

Troubleshoot MySQL data source issues

This document provides solutions to common issues you may encounter when configuring or using the MySQL data source in Grafana.

Connection errors

These errors occur when Grafana cannot establish or maintain a connection to the MySQL server.

Unable to connect to the server

Error message: “dial tcp: connection refused” or “Could not connect to MySQL”

Cause: Grafana cannot establish a network connection to the MySQL server.

Solution:

Verify that the MySQL server is running and accessible.
Check that the host and port are correct in the data source configuration. The default MySQL port is 3306.
Ensure there are no firewall rules blocking the connection between Grafana and MySQL.
Verify that MySQL is configured to allow remote connections by checking the bind-address setting in your MySQL configuration.
For Grafana Cloud, ensure you have configured Private data source connect if your MySQL instance isn’t publicly accessible.

Connection timeout

Error message: “Connection timed out” or “I/O timeout”

Cause: The connection to MySQL timed out before receiving a response.

Solution:

Check the network latency between Grafana and MySQL.
Verify that MySQL isn’t overloaded or experiencing performance issues.
Check if any network devices (load balancers, proxies) are timing out the connection.
Increase the wait_timeout setting in MySQL if connections are timing out during idle periods.

TLS/SSL connection failures

Error message: “TLS handshake failed” or “x509: certificate verify failed”

Cause: There is a mismatch between the TLS settings in Grafana and what the MySQL server supports or requires.

Solution:

Verify that the MySQL server has a valid SSL certificate if encryption is enabled.
Check that the certificate is trusted by the Grafana server.
If using a self-signed certificate, enable With CA Cert and provide the root certificate under TLS/SSL Root Certificate.
To bypass certificate validation (not recommended for production), enable Skip TLS Verification in the data source configuration.
Ensure the SSL certificate hasn’t expired.

Connection reset by peer

Error message: “Connection reset by peer” or “EOF”

Cause: The MySQL server closed the connection unexpectedly.

Solution:

Check the max_connections setting on the MySQL server to ensure it isn’t being exceeded.
Verify the wait_timeout and interactive_timeout settings in MySQL aren’t set too low.
Increase the Max lifetime setting in Grafana’s data source configuration to be lower than the MySQL wait_timeout.
Check MySQL server logs for any errors or connection-related messages.

Authentication errors

These errors occur when there are issues with authentication credentials or permissions.

Access denied for user

Error message: “Access denied for user ‘username’@‘host’” or “Authentication failed”

Cause: The authentication credentials are invalid or the user doesn’t have permission to connect from the Grafana server’s host.

Solution:

Verify that the username and password are correct.
Check that the user exists in MySQL and is enabled.
Ensure the user has permission to connect from the Grafana server’s IP address. MySQL restricts access based on the connecting host:
SQL
```
SELECT user, host FROM mysql.user WHERE user = 'your_user';
```
If necessary, create a user that can connect from the Grafana server:
SQL
```
CREATE USER 'grafana'@'grafana_server_ip' IDENTIFIED BY 'password';
```
If using the mysql_native_password authentication plugin, ensure it’s enabled on the server.

Cannot access database

Error message: “Access denied for user ‘username’@‘host’ to database ‘dbname’”

Cause: The authenticated user doesn’t have permission to access the specified database.

Solution:

Verify that the database name is correct in the data source configuration.

Ensure the user has the required permissions on the database:

GRANT SELECT ON your_database.* TO 'grafana'@'grafana_server_ip';
FLUSH PRIVILEGES;

For production environments, grant permissions only on specific tables:
SQL
```
GRANT SELECT ON your_database.your_table TO 'grafana'@'grafana_server_ip';
```

PAM authentication issues

Error message: “Authentication plugin ‘auth_pam’ cannot be loaded” or cleartext password errors

Cause: PAM (Pluggable Authentication Modules) authentication requires cleartext password transmission.

Solution:

Enable Allow Cleartext Passwords in the data source configuration if using PAM authentication.
Ensure TLS is enabled to protect password transmission when using cleartext passwords.
Verify that the PAM plugin is correctly installed and configured on the MySQL server.

Query errors

These errors occur when there are issues with query syntax or configuration.

Time column not found or invalid

Error message: “Could not find time column” or time series visualization shows no data

Cause: The query doesn’t return a properly formatted time column for time series visualization.

Solution:

Ensure your query includes a column named time when using the Time series format.
Use the $__time() macro to convert your date column: $__time(your_date_column).
Verify the time column is of a valid MySQL date/time type (DATETIME, TIMESTAMP, DATE) or contains Unix epoch values.
Ensure the result set is sorted by the time column using ORDER BY.

Macro expansion errors

Error message: “Error parsing query” or macros appear unexpanded in the query

Cause: Grafana macros are being used incorrectly.

Solution:

Verify macro syntax: use $__timeFilter(column) not $_timeFilter(column).
Check that the column name passed to macros exists in your table.
View the expanded query by clicking Generated SQL after running the query to debug macro expansion.
Ensure backticks are used for reserved words or special characters in column names: $__timeFilter(\time-column`)`.

Timezone and time shift issues

Cause: Time series data appears shifted or doesn’t align with expected times.

Solution:

Store timestamps in UTC in your database to avoid timezone issues.
Time macros ($__time, $__timeFilter, etc.) always expand to UTC values.
Set the Session Timezone in the data source configuration to match your data’s timezone, or use +00:00 for UTC.

If your timestamps are stored in local time, convert them to UTC in your query:

SELECT
  CONVERT_TZ(your_datetime_column, 'Your/Timezone', 'UTC') AS time,
  value
FROM your_table

Query returns too many rows

Error message: “Result set too large” or browser becomes unresponsive

Cause: The query returns more data than can be efficiently processed.

Solution:

Add time filters using $__timeFilter(column) to limit data to the dashboard time range.
Use aggregations (AVG, SUM, COUNT) with GROUP BY instead of returning raw rows.
Add a LIMIT clause to restrict results: SELECT ... LIMIT 1000.
Use the $__timeGroup() macro to aggregate data into time intervals.

Syntax error in SQL statement

Error message: “You have an error in your SQL syntax” followed by specific error details

Cause: The SQL query contains invalid syntax.

Solution:

Check for missing or extra commas, parentheses, or quotes.
Ensure reserved words used as identifiers are enclosed in backticks: `table`, `select`.
Verify that template variable syntax is correct: $variable or ${variable}.
Test the query directly in a MySQL client to isolate Grafana-specific issues.

Unknown column in field list

Error message: “Unknown column ‘column_name’ in ‘field list’”

Cause: The specified column doesn’t exist in the table or is misspelled.

Solution:

Verify the column name is spelled correctly.
Check that the column exists in the specified table.
If the column name contains special characters or spaces, enclose it in backticks: `column-name`.
Ensure the correct database is selected if you’re referencing columns without the full table path.

Performance issues

These issues relate to slow queries or high resource usage.

Slow query execution

Cause: Queries take a long time to execute.

Solution:

Reduce the dashboard time range to limit data volume.
Add indexes to columns used in WHERE clauses and time filters:
SQL
```
CREATE INDEX idx_time ON your_table(time_column);
```
Use aggregations instead of returning individual rows.
Increase the Min time interval setting to reduce the number of data points.

Review the query execution plan using EXPLAIN to identify bottlenecks:

EXPLAIN SELECT * FROM your_table WHERE time_column > NOW() - INTERVAL 1 HOUR;

Connection pool exhaustion

Error message: “Too many connections” or “Connection pool exhausted”

Cause: Too many concurrent connections to the database.

Solution:

Increase the Max open connection limit in the data source configuration.
Enable Auto (max idle) to automatically manage idle connections.
Reduce the number of panels querying the same data source simultaneously.
Check for long-running queries that might be holding connections.

Increase the max_connections setting in MySQL if necessary:

SHOW VARIABLES LIKE 'max_connections';
SET GLOBAL max_connections = 200;

Query timeout

Error message: “Query execution was interrupted” or “Lock wait timeout exceeded”

Cause: The query takes too long and exceeds the configured timeout.

Solution:

Optimize the query by adding appropriate indexes.
Reduce the amount of data being queried by narrowing the time range.
Use aggregations to reduce the result set size.
Check for table locks that might be blocking the query.

Other common issues

The following issues don’t produce specific error messages but are commonly encountered.

Template variable queries fail

Cause: Variable queries return unexpected results or errors.

Solution:

Verify the variable query syntax is valid SQL that returns a single column.
Check that the data source connection is working.
Ensure the user has permission to access the tables referenced in the variable query.
Test the query in the query editor before using it as a variable query.

Data appears incorrect or misaligned

Cause: Data formatting or type conversion issues.

Solution:

Use explicit column aliases to ensure consistent naming: SELECT value AS metric.
Verify numeric columns are actually numeric types, not strings.
Check for NULL values that might affect aggregations.
Use the FILL option in $__timeGroup() macro to handle missing data points.

Special characters in database or table names

Cause: Queries fail when tables or databases contain reserved words or special characters.

Solution:

Enclose identifiers with special characters in backticks: `my-database`.`my-table`.
The query editor automatically handles this for selections, but manual queries require backticks.
Avoid using reserved words as identifiers when possible.

An unexpected error happened

Error message: “An unexpected error happened”

Cause: A general error occurred that doesn’t have a specific error message.

Solution:

Check the Grafana server logs for more details about the error.
Verify all data source configuration settings are correct.
Test the connection using the Save & test button.
Ensure the MySQL server is accessible and responding to queries.
For Grafana Cloud customers, contact support for assistance.

Get additional help

If you continue to experience issues after following this troubleshooting guide:

Check the Grafana community forums for similar issues.
Review the Grafana GitHub issues for known bugs.
Enable debug logging in Grafana to capture detailed error information.
Check MySQL error logs for additional details.
Contact Grafana Support if you’re an Enterprise or Cloud customer.

When reporting issues, include:

Grafana version
MySQL version
Error messages (redact sensitive information)
Steps to reproduce
Relevant query examples (redact sensitive data)

MySQL data source on Grafana Labs

Configure the MySQL data source

Configure the MySQL data source

Before you begin

Database user permissions

Add the MySQL data source

MySQL configuration options

Additional settings

Min time interval

Provision the data source

MySQL provisioning examples

Configure with Terraform

Terraform example

Next steps

MySQL query editor

MySQL query editor

MySQL query editor components

MySQL Builder mode

MySQL Code mode

Macros

Table SQL queries

Time series queries

Template variables

Annotations

Alerting

MySQL template variables

MySQL template variables

Query variable

Key/value variables

Nested variables

Filter results with __searchFilter

Use variables in queries

Disable quoting for multi-value variables

MySQL annotations

MySQL annotations

Before you begin

Create an annotation query

Query columns

Example queries

Basic annotation with epoch time

Annotation with a single tag

Range annotation with start and end time

Annotation with native SQL datetime

Deployment annotations

Maintenance window annotations

Macros

Best practices

MySQL alerting

MySQL alerting

Before you begin

Supported query types

Query format requirements

Create an alert rule

Example alert queries

Alert on high error count

Alert on average response time

Alert on low order volume

Alert on disk usage percentage

Limitations

Template variables not supported

Table format not supported

Query timeout

Best practices

Troubleshoot MySQL data source issues

Troubleshoot MySQL data source issues

Connection errors

Unable to connect to the server

Connection timeout

TLS/SSL connection failures

Connection reset by peer

Authentication errors

Access denied for user

Cannot access database

PAM authentication issues

Query errors

Time column not found or invalid

Macro expansion errors

Timezone and time shift issues

Query returns too many rows

Syntax error in SQL statement

Filter results with `__searchFilter`