Microsoft SQL Server data source on Grafana Labs

Configure the Microsoft SQL Server data source

Tue, 18 Aug 2026 10:15:08 +0000

Configure the Microsoft SQL Server data source

This document provides instructions for configuring the Microsoft SQL Server data source and explains available configuration options. For general information on adding and managing data sources, refer to Grafana data sources and Data source management.

Note
This page documents the Microsoft SQL Server data source, which lets you query an existing SQL Server database and visualize the results in Grafana. This is different from the Microsoft SQL Server integration (available in Grafana Cloud), which uses Grafana Alloy to collect performance metrics about your SQL Server instance (CPU, memory, connections, and similar). If you want to monitor the health of SQL Server itself, refer to the integration documentation instead.

Before you begin

Before configuring the Microsoft SQL Server data source, ensure you have the following:

Grafana permissions: You must have the Organization administrator role to add and configure data sources. Users with the Editor or Viewer role cannot access the data source configuration form unless granted additional permissions through RBAC. Organization administrators can also configure the data source via YAML with the Grafana provisioning system.
A running SQL Server instance: Microsoft SQL Server 2012 or newer, Azure SQL Database, or Azure SQL Managed Instance.
Network access: Grafana must be able to reach your SQL Server. The default port is 1433.
Authentication credentials: Depending on your authentication method, you need one of:
- SQL Server login credentials (username and password).
- Windows/Kerberos credentials and configuration (not supported in Grafana Cloud).
- Azure Entra ID app registration or managed identity.
Security certificates: If using encrypted connections, gather any necessary TLS/SSL certificates.

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

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

Add the MSSQL data source

To add the MSSQL data source, complete the following steps:

Click Connections in the left-side menu.
Click Add new connection
Type Microsoft SQL Server in the search bar.
Select Microsoft SQL Server under data source.
Click Add new data source in the upper right.

Grafana takes you to the Settings tab, where you will set up your Microsoft SQL Server configuration.

Configure the data source in the UI

Following are configuration options for the Microsoft SQL Server data source.

Warning
Kerberos is not supported in Grafana Cloud.

Setting	Description
Name	The data source name. Sets the name you use to refer to the data source in panels and queries. Examples: `MSSQL-1`, `MSSQL_Sales1`.
Default	Toggle to select as the default name in dashboard panels. When you go to a dashboard panel, this will be the default selected data source.

Connection:

Setting	Description
Host	Sets the IP address or hostname (and optional port) of your MSSQL instance. The default port is `0`, which uses the driver’s default. You can include additional connection properties (for example, `ApplicationIntent`) by separating them with semicolons (`;`).
Database	Sets the name of the MSSQL database to connect to.

Caution
If you add ApplicationIntent=ReadOnly to the Host field to route queries to a read-only replica, be aware that read-only replicas may be significantly slower than the primary. This can cause dashboard load times of several minutes. Only use ApplicationIntent=ReadOnly if your replica is sized for the query workload and you’ve tested performance.

TLS/SSL encryption:

The Encrypt setting determines whether and to what extent a secure TLS/SSL connection is negotiated with the server.

Encrypt setting	Description	When to use
Disable	Data sent between the client and server is not encrypted.	Legacy environments where encryption isn’t supported or required. Not recommended for production.
False	The default setting. Only the login packet is encrypted; all other data is sent unencrypted.	Development environments or when SQL Server doesn’t have a valid certificate.
True	All data sent between the client and server is encrypted.	Production environments. Required for Azure SQL Database.

When Encrypt is set to True, the following additional TLS options are available:

Setting	Description	Default
Skip TLS Verify	If enabled, the server’s certificate chain and hostname aren’t validated. Equivalent to `trustServerCertificate=true` in the connection string.	Disabled
TLS/SSL Root Certificate	Path to a PEM-encoded CA certificate file used to verify the server’s certificate. Required when the SQL Server uses a certificate signed by a private CA.	System CA bundle
Hostname in server certificate	The expected hostname in the server’s TLS certificate. Use this when the certificate’s Common Name (CN) or Subject Alternative Name (SAN) doesn’t match the configured hostname (for example, when connecting through a load balancer or PDC).	Value from Host field

Choosing the right encryption configuration:

Scenario	Encrypt	Skip TLS Verify	Root Certificate	Notes
Azure SQL Database	True	No	Not needed	Azure SQL always requires encryption and uses a publicly trusted certificate.
SQL Server with public CA certificate	True	No	Not needed	Certificate is already in the system trust store.
SQL Server with private/self-signed certificate	True	No	Path to CA cert	Upload or reference the CA certificate that signed the SQL Server certificate.
SQL Server with unverified certificate (testing only)	True	Yes	Not needed	Skips certificate validation entirely. Don’t use in production.
SQL Server 2008/2008R2 without valid certificate	Disable or False	N/A	N/A	Older versions may not support TLS negotiation.
Grafana Cloud with PDC	True	No	Not needed (usually)	PDC tunnels are encrypted at the SSH layer; the TLS certificate must still be valid from the PDC agent’s perspective.

Note
If you’re using an older version of Microsoft SQL Server like 2008 or 2008R2, you may need to set Encrypt to Disable or False to connect.

Caution
Grafana builds using BoringCrypto (FIPS-compliant builds) enforce FIPS 140-3 cipher requirements. If your SQL Server only supports older cipher suites (for example, TLS 1.0 or RC4-based ciphers), connections from a FIPS-enabled Grafana instance fail with a TLS handshake error. Upgrade your SQL Server TLS configuration to support TLS 1.2 with FIPS-approved cipher suites.

Authentication:

Authentication Type	Description	Credentials / Fields
SQL Server Authentication	Default method to connect to MSSQL. Use a SQL Server or Windows login in `DOMAIN\User` format.	Username: SQL Server username. Password: SQL Server password.
Windows Authentication (Integrated Security)	Uses the logged-in Windows user’s credentials via single sign-on. Available only when SQL Server allows Windows Authentication.	No input required; uses the logged-in Windows user’s credentials.
Windows AD (Username/Password)	Authenticates a domain user with their Active Directory username and password.	Username: `user@example.com`. Password: Active Directory password.
Windows AD (Keytab)	Authenticates a domain user using a keytab file.	Username: `user@example.com`. Keytab file path: Path to your keytab file.
Windows AD (Credential Cache)	Uses a Kerberos credential cache already loaded in memory (for example, from a prior `kinit` command). No file needed.	Credential cache path: Path to in-memory credential (for example, `/tmp/krb5cc_1000`).
Windows AD (Credential Cache File)	Authenticates a domain user using a credential cache file (`.ccache`).	Username: `user@example.com`. Credential cache file path: for example, `/home/grot/cache.json`.
Azure Entra ID (formerly Azure AD) Authentication	Authenticates the data source using Azure authentication methods.	Details on the supported authentication methods and how to configure them can be found in the Azure authentication section.

Note
As of Grafana v13.0, passwords and usernames that contain semicolons (;) or closing braces (}) are handled correctly. If you previously encountered connection failures due to special characters in credentials, upgrade to Grafana v13.0 or later.

Additional settings:

Additional settings are optional settings you configure for more control over your data source. This includes connection limits, connection timeout, group-by time interval, and Secure Socks Proxy.

Connection limits:

Grafana maintains a connection pool for each configured MSSQL data source. These settings control pool behavior and directly affect performance, especially under concurrent load from dashboards and alerting.

Setting	Description
Max open	The maximum number of open connections to the database. If set to `0`, there is no limit. If `max open` is greater than `0` and less than `max idle`, `max idle` is adjusted to match.
Auto max idle	When enabled, automatically sets `max idle` to match `max open`. If `max open` isn’t set, it defaults to `100`.
Max idle	The maximum number of idle connections in the pool. If `max open` is set and is lower than `max idle`, then `max idle` is reduced to match. If set to `0`, no idle connections are retained.
Max lifetime	The maximum time (in seconds) a connection can be reused before being closed and replaced. If set to `0`, connections are reused indefinitely.

Caution
If Max open is set too low, concurrent dashboard panels and alert rule evaluations compete for connections. Alerting queries may fail with “failed to connect to server” while dashboards continue to work, because alert evaluations use a separate execution path that can’t wait indefinitely for a free connection. Increase Max open if you see intermittent alert failures.

Connection details:

Setting	Description
Min time interval	Specifies the lower bound for the auto-generated `GROUP BY` time interval. Grafana recommends matching this value to the data write frequency—for example, `1m` if data is written every minute. Refer to Min time interval for details.
Connection timeout	Specifies the maximum number of seconds to wait when attempting to connect to the database before timing out. A value of `0` (the default) disables the timeout.

Windows AD Advanced settings:

Setting	Description	Default
UDP Preference Limit	Defines the maximum packet size (in bytes) that Kerberos libraries attempt to send over UDP before retrying with TCP. A value of `1` forces all communication to use TCP.	`1` (always use TCP)
DNS Lookup KDC	Controls whether DNS `SRV` records are used to locate Key Distribution Centers (KDCs) and other servers for the realm.	`true`
krb5 config file path	Specifies the path to the Kerberos configuration file used by the MIT krb5 package.	`/etc/krb5.conf`

Note
Windows AD (Kerberos) authentication is only available for self-managed Grafana installations. It is not supported in Grafana Cloud. For Grafana Cloud deployments connecting to SQL Server, use SQL Server Authentication or Azure Entra ID.

Kerberos SPN requirements:

For Kerberos authentication to succeed, a Service Principal Name (SPN) must be registered for the SQL Server instance that matches the hostname Grafana uses to connect. This is especially important when connecting through Availability Group Listeners or DNS aliases.

setspn -S MSSQLSvc/<SQL_SERVER_FQDN>:1433 <DOMAIN>\<SERVICE_ACCOUNT>
setspn -S MSSQLSvc/<SQL_SERVER_FQDN> <DOMAIN>\<SERVICE_ACCOUNT>

If Grafana connects through a Listener or alias, register an additional SPN for that name. Verify registered SPNs with setspn -L <DOMAIN>\<SERVICE_ACCOUNT>.

Connect to on-premises SQL Server from Grafana Cloud

If your SQL Server instance is in a private network (on-premises, VPN, or VPC), Grafana Cloud cannot reach it directly over the internet. You must use Private data source connect (PDC) to establish a secure tunnel between your Grafana Cloud stack and your private network.

Note
PDC is required for any SQL Server that isn’t publicly accessible from the internet. Firewall allowlisting alone is not sufficient because Grafana Cloud doesn’t use static IP addresses for data source connections.

Network prerequisites:

Port 22 (SSH): The PDC agent on your network must be able to reach the Grafana Cloud PDC endpoint over port 22 for the SSH tunnel.
Port 1433 (SQL Server): The PDC agent must be able to reach your SQL Server instance on port 1433 (or your custom SQL Server port).
DNS resolution: The PDC agent must be able to resolve the SQL Server hostname from within your private network.

Set up PDC for Microsoft SQL Server:

In your Grafana Cloud stack, navigate to Connections > Private data source connect.
Create a new PDC connection or use an existing one.
Install and configure the PDC agent on a host within your private network that has access to the SQL Server instance. For detailed instructions, refer to Configure Grafana private data source connect (PDC).
Return to the Microsoft SQL Server data source configuration.
Under Private data source connect, select your PDC connection from the drop-down.
Enter the SQL Server hostname as it’s resolvable from within your private network (not a public DNS name).
Click Save & test to verify connectivity.

Click Manage private data source connect to open your PDC connection page and view your configuration details.

For more information about PDC, refer to Private data source connect (PDC).

Caution
If you previously connected using a self-managed Grafana instance and are migrating to Grafana Cloud, you must configure PDC before your private SQL Server is accessible. Direct network access methods that worked with self-managed Grafana (VPN peering, private endpoints) don’t apply to Grafana Cloud.

After configuring your MSSQL data source options, click Save & test at the bottom to test the connection. You should see a confirmation dialog box that says:

Database Connection OK

Azure Entra ID (formerly Azure AD) Authentication

The following Azure authentication methods are supported:

App Registration (service principal)
Managed Identity
Current User authentication
Azure Entra Password

The Azure SQL Server that you are connecting to must support Azure Entra authentication. For configuration details, refer to the Azure SQL documentation.

Required server configuration

Before you can use any Azure Entra ID authentication method, you must enable Azure authentication in the Grafana server configuration. Add the following to your grafana.ini or custom.ini file:

[azure]
azure_auth_enabled = true

Depending on the method you choose, additional flags are required (documented in each section below). After changing the .ini file, restart the Grafana server for the changes to take effect.

Current User authentication

This is the recommended authentication mechanism when working with SQL Server instances that are hosted in Azure. It allows users to be authenticated to and query the database using their own credentials rather than long-lived credentials.

This authentication method requires your Grafana instance to be configured with Azure Entra ID (formerly Active Directory) authentication for login. With Azure Entra ID login, this method can be used to forward the currently logged in user’s credentials to the data source. The users credentials will then be used when requesting data from the data source. For details on how to configure your Grafana instance using Azure Entra refer to the documentation.

Note
Additional configuration is required to ensure that the App Registration used to login a user via Azure provides an access token with the permissions required by the data source.

The App Registration must be configured to issue both Access Tokens and ID Tokens.

In the Azure Portal, open the App Registration that requires configuration.

Select Authentication in the side menu.

Under Implicit grant and hybrid flows check both the Access tokens and ID tokens boxes.

Save the changes to ensure the App Registration is updated.

The App Registration must also be configured with additional API Permissions to provide authenticated users with access to the APIs utilised by the data source.

In the Azure Portal, open the App Registration that requires configuration.

Select API Permissions in the side menu.

Ensure the openid, profile, email, and offline_access permissions are present under the Microsoft Graph section. If not, they must be added.

Select Add a permission and choose the following permissions. They must be added individually. Refer to the Azure documentation for more information.

Select APIs my organization uses > Search for Azure SQL and select it > Delegated permissions > user_impersonation > Add permissions

After all permissions have been added, the Azure authentication section in Grafana must be updated. The scopes section must be updated to include the .default scope to ensure that a token with access to all APIs declared on the App Registration is requested by Grafana. After updated the scopes value should equal: .default openid email profile.

This method of authentication doesn’t inherently support all backend functionality as a user’s credentials won’t be in scope. Affected functionality includes alerting, reporting, and recorded queries. Also, note that query and resource caching is disabled by default for data sources using current user authentication.

To enable current user authentication for Grafana:

Set the user_identity_enabled flag in the [azure] section of the Grafana server configuration.
ini
```
[azure]
user_identity_enabled = true
```
In the SQL Server data source configuration, set Authentication to Azure AD Authentication and the Azure Authentication type to Current User.

App Registration

Use an app registration (service principal) to authenticate the data source with a client ID and secret. This is the recommended method for automated, non-interactive access to Azure SQL.

Prerequisites:

An app registration created in Azure Entra. For instructions, refer to the Azure documentation for service principals.
The tenant ID, client (application) ID, and a client secret from the app registration.

Step 1: Add the app registration as a database user

Connect to your Azure SQL database as a user with administrative permissions (the user must have the ability to read your Azure Entra directory, for example, by possessing the Directory Readers role).
Run the following SQL to create a user for the app registration:
SQL
```
CREATE USER [<APP_REGISTRATION_NAME>] FROM EXTERNAL PROVIDER;
```
Grant the created user appropriate permissions. Grafana recommends read-only access:
SQL
```
ALTER ROLE db_datareader ADD MEMBER [<APP_REGISTRATION_NAME>];
```

Step 2: Configure the Grafana server

Ensure azure_auth_enabled is set in your grafana.ini:

[azure]
azure_auth_enabled = true

Step 3: Configure the data source

In the SQL Server data source configuration, set Authentication to Azure AD Authentication and the Azure Authentication type to App Registration.
Set Azure Cloud to Azure (for the Azure public cloud).
Enter the Directory (tenant) ID, Application (client) ID, and Client Secret from your app registration.

Managed Identity

Note
Managed Identity is available only in Azure Managed Grafana or self-managed Grafana deployed in Azure. It is not available in Grafana Cloud.

You can use managed identity to configure SQL Server in Grafana if you host Grafana in Azure (such as an App Service or with Azure Virtual Machines) and have managed identity enabled on your VM. This lets you securely authenticate data sources without manually configuring credentials. For details on Azure managed identities, refer to the Azure documentation.

To enable managed identity for Grafana:

Set both azure_auth_enabled and managed_identity_enabled in the [azure] section of the Grafana server configuration:
ini
```
[azure]
azure_auth_enabled = true
managed_identity_enabled = true
```
In the SQL Server data source configuration, set Authentication to Azure AD Authentication and the Azure Authentication type to Managed Identity.

This hides the directory ID, application ID, and client secret fields, and the data source uses managed identity to authenticate to SQL Server.
Optionally, set managed_identity_client_id in the [azure] section to use a user-assigned managed identity instead of the default system-assigned identity.

Ensure that the managed identity is added to your Azure SQL instance as a user.

Azure Entra Password

Warning
Azure Entra Password is not a recommended authentication mechanism as it requires configuration using a single users password. Consider an alternative authentication method such as current user authentication or app registration.

You can connect to an Azure SQL database using the username and password of a user that has permissions in the desired database. This also requires an app registration to be configured with access to the database.

To enable Azure Entra password for Grafana:

Set the azure_entra_password_credentials_enabled flag in the [azure] section of the Grafana server configuration.
ini
```
[azure]
azure_entra_password_credentials_enabled = true
```
In the SQL Server data source configuration, set Authentication to Azure AD Authentication and the Azure Authentication type to Azure Entra Password.
Set the User ID value to the username of the user in the Azure SQL database.
Set the Application Client ID to the client ID of the app registration that has been added to the Azure SQL database
Set the Password value to the password of the user in the Azure SQL database.

Min time interval

The Min time interval setting defines a lower limit for the $__interval and [$__interval_ms][add-template-variables-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

Grafana recommends setting this value to match your Microsoft SQL Server write frequency. For example, use 1m if Microsoft SQL Server writes data every minute.

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

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 does not 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 MSSQL user with restricted permissions.

CREATE USER grafanareader WITH PASSWORD 'password'
GRANT SELECT ON dbo.YourTable3 TO grafanareader

Also, ensure that the user doesn’t have any unwanted privileges from the public role.

Diagnose connection issues

If you use older versions of Microsoft SQL Server, such as 2008 and 2008R2, you might need to disable encryption before you can connect the data source.

Grafana recommends that you use the latest available service pack for optimal compatibility.

Provision the data source

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

Provisioning example

apiVersion: 1

datasources:
  - name: MSSQL
    type: mssql
    url: localhost:1433
    user: grafana
    jsonData:
      database: grafana
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
      connectionTimeout: 0
      encrypt: 'false'
    secureJsonData:
      password: 'Password!'

Configure with Terraform

You can configure the Microsoft SQL Server 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 Microsoft SQL Server data source:

resource "grafana_data_source" "mssql" {
  name = "MSSQL"
  type = "mssql"
  url  = "localhost:1433"
  user = "grafana"

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

  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 Microsoft SQL Server data source, you can:

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

Microsoft SQL Server query editor

Tue, 18 Aug 2026 10:15:08 +0000

Microsoft SQL Server query editor

The MSSQL query editor lets you write Transact-SQL queries directly in Grafana, with built-in macros and formatting options designed for time series and table visualizations. You can open it from Explore or from any dashboard panel in edit mode.

This page covers MSSQL-specific query features. For general querying concepts shared across all data sources, refer to Query and transform data. For Transact-SQL syntax, refer to Write Transact-SQL statements and Transact-SQL reference in the Microsoft documentation.

The Microsoft SQL Server query editor has two modes:

To switch between the editor modes, select the corresponding Builder and Code tabs in the upper right.

Warning
When switching from Code mode to Builder mode, any changes made to your SQL query aren’t saved and aren’t shown in the builder interface. You can choose to copy your code to the clipboard or discard the changes.

To run a query, select Run query in the upper right of the editor.

In addition to writing queries, the query editor also allows you to create and use:

Builder mode

Builder mode allows you to build queries using a visual interface. This mode is great for users who prefer a guided query experience or are just getting started with SQL.

The following components help you build a T-SQL query:

Format - Select a format response from the drop-down for the MSSQL query. The default is Table. Refer to Table queries and Time series queries for more information and examples. If you select the Time series format option, you must include a time column.
Dataset - Select a database to query from the drop-down. Grafana automatically populates the drop-down with all databases the user has access to. If a database is set in the Database field on the data source configuration page or via a provisioning file, users are limited to querying only that database.

Note that tempdb, model, msdb, and master system databases are not included in the query editor drop-down.
Table - Select a table from the drop-down. After selecting a database, the next drop-down displays all available tables in that database.
Data operations - Optional. Select an aggregation or a macro from the drop-down. You can add multiple data operations by clicking the + sign. Click the garbage can icon to remove data operations.
- Column - Select a column on which to run the aggregation.
- Interval - Select an interval from the drop-down. You’ll see this option when you choose a time group macro from the drop-down.
- Fill - Optional. Add a FILL method to populate missing time intervals with default values (such as NULL, 0, or a specified value) when no data exists for those intervals. This ensures continuity in the time series, avoiding gaps in visualizations.
- 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 by additional 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, use the AND or OR operators to define how conditions are evaluated. AND requires all conditions to be true, while OR requires any condition to be true. Use the second drop-down to select the filter value. To remove a filter, click the X icon next to it. If you select a date-type column, you can use macros from the operator list and choose timeFilter to insert the $\_\_timeFilter macro into your query with the selected date column.
  
  After selecting a date type column, you can choose Macros from the operators list and select timeFilter, which adds the $\_\_timeFilter macro to the query with the selected date column. Refer to Macros for more information.
Group - Toggle to add a 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.

For additional detail about using formats, refer to Table queries and Time series queries.

Code mode

Code mode lets you build complex queries using a text editor with helpful features like autocompletion and syntax highlighting.

This mode is ideal for advanced users who need full control over the SQL query or want to use features not available in visual query mode. It’s especially useful for writing subqueries, using macros, or applying advanced filtering and formatting. You can switch back to visual mode, but note that some custom queries may not be fully compatible.

Code mode has several features in a toolbar located in the editor’s lower-right corner.

To reformat the query, click the brackets button ({}).
To expand the code editor, click the chevron button pointing downward.
To run the query, click the Run query button or use the keyboard shortcut Ctrl/Cmd + Enter/Return.

Use autocompletion

Code mode’s autocompletion feature works automatically while typing. To manually trigger autocompletion, use the keyboard shortcut Ctrl/Cmd + Space.

Code mode supports autocompletion of tables, columns, SQL keywords, standard SQL functions, Grafana template variables, and Grafana macros.

Note
You can’t autocomplete columns until you’ve specified a table.

Macros

To simplify syntax and to allow for dynamic components, such as date range filters, you can add macros to your query.

Use macros in the SELECT clause to simplify the creation of time series queries. From the Data operations drop-down, choose a macro such as $\_\_timeGroup or $\_\_timeGroupAlias. Then, select a time column from the Column drop-down and a time interval from the Interval drop-down. This generates a time-series query based on your selected time grouping.

Warning
Time macros ($__time, $__timeFilter, etc.) don’t support time zone parameters in Microsoft SQL Server and always expand to UTC values. If your timestamps aren’t stored in UTC (common with datetime/datetime2 types), convert them to UTC in your SQL query using AT TIME ZONE … AT TIME ZONE 'UTC' rather than passing a time zone argument to a macro.

Macro	Description
`$__time(dateColumn)`	Renames the specified column to `_time`. Example: `dateColumn AS time`
`$__timeEpoch(dateColumn)`	Converts a `DATETIME` column to a Unix timestamp and renames it to `_time`. Example: `DATEDIFF(second, '1970-01-01', dateColumn) AS time`
`$__timeFilter(dateColumn)`	Adds a time range filter for the specified column. Example: `dateColumn BETWEEN '2017-04-21T05:01:17Z' AND '2017-04-21T05:06:17Z'`
`$__timeFrom()`	Returns the start of the current time range. Example: `'2017-04-21T05:01:17Z'`
`$__timeTo()`	Returns the end of the current time range. Example: `'2017-04-21T05:06:17Z'`
`$__timeGroup(dateColumn, '5m'[, fillValue])`	Groups the specified time column into intervals (for example, 5 minutes). Optionally fills gaps with a value like `0`, `NULL`, or `previous`. Example: `CAST(ROUND(DATEDIFF(second, '1970-01-01', time_column)/300.0, 0) AS bigint) * 300`
`$__timeGroup(dateColumn, '5m', 0)`	Same as above, with `0` used to fill missing data points.
`$__timeGroup(dateColumn, '5m', NULL)`	Same as above, with `NULL` used for missing data points.
`$__timeGroup(dateColumn, '5m', previous)`	Same as above, using the previous value to fill gaps. If no previous value exists, `NULL` is used.
`$__timeGroupAlias(dateColumn, '5m')`	Same as `$__timeGroup`, but also adds an alias to the resulting column.
`$__unixEpochFilter(dateColumn)`	Adds a time range filter using Unix timestamps. Example: `dateColumn > 1494410783 AND dateColumn < 1494497183`
`$__unixEpochFrom()`	Returns the start of the current time range as a Unix timestamp. Example: `1494410783`
`$__unixEpochTo()`	Returns the end of the current time range as a Unix timestamp. Example: `1494497183`
`$__unixEpochNanoFilter(dateColumn)`	Adds a time range filter using nanosecond-precision Unix timestamps. Example: `dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872`
`$__unixEpochNanoFrom()`	Returns the start of the current time range as a nanosecond Unix timestamp. Example: `1494410783152415214`
`$__unixEpochNanoTo()`	Returns the end of the current time range as a nanosecond Unix timestamp. Example: `1494497183142514872`
`$__unixEpochGroup(dateColumn, '5m', [fillMode])`	Same as `$__timeGroup`, but for Unix timestamps. Optional `fillMode` controls how to handle missing points.
`$__unixEpochGroupAlias(dateColumn, '5m', [fillMode])`	Same as above, but adds an alias to the grouped column.

View the interpolated query

The query editor includes a Generated SQL link that appears after you run a query while editing a panel. Click this link to view the raw interpolated SQL that Grafana executed, including any macros that were expanded during query processing.

Table queries

To create a Table query, set the Format option in the query editor to Table. This allows you to write any valid SQL query, and the Table panel displays the results using the returned columns and rows.

Example:

CREATE TABLE [event] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

CREATE TABLE [mssql_types] (
  c_bit bit, c_tinyint tinyint, c_smallint smallint, c_int int, c_bigint bigint, c_money money, c_smallmoney smallmoney, c_numeric numeric(10,5),
  c_real real, c_decimal decimal(10,2), c_float float,
  c_char char(10), c_varchar varchar(10), c_text text,
  c_nchar nchar(12), c_nvarchar nvarchar(12), c_ntext ntext,
  c_datetime datetime,  c_datetime2 datetime2, c_smalldatetime smalldatetime, c_date date, c_time time, c_datetimeoffset datetimeoffset
)

INSERT INTO [mssql_types]
SELECT
  1, 5, 20020, 980300, 1420070400, '$20000.15', '£2.15', 12345.12,
  1.11, 2.22, 3.33,
  'char10', 'varchar10', 'text',
  N'☺nchar12☺', N'☺nvarchar12☺', N'☺text☺',
  GETDATE(), CAST(GETDATE() AS DATETIME2), CAST(GETDATE() AS SMALLDATETIME), CAST(GETDATE() AS DATE), CAST(GETDATE() AS TIME), SWITCHOFFSET(CAST(GETDATE() AS DATETIMEOFFSET), '-07:00')

Example query with output:

SELECT * FROM [mssql_types]

Use the keyword AS to define an alias in your query to rename a column or table.

Example query with output:

SELECT
  c_bit AS [column1], c_tinyint AS [column2]
FROM
  [mssql_types]

Time series queries

Note
Store timestamps in UTC to avoid issues with time shifts in Grafana when using non-UTC timezones.

To create a time series query, set the Format option in the query editor to Time series. The query must include a column named time, which should contain either an SQL datetime value or a numeric value representing Unix epoch time in seconds. The result set must be sorted by the time column for panels to visualize the data correctly.

A time series query returns results in wide data frame format.

Any column except time or of the type string transforms into value fields in the data frame query result.
Any string column transforms into field labels in the data frame query result.

You can enable macro support in the SELECT clause to simplify time series query creation. Use the Data operations drop-down to choose a macro such as $\_\_timeGroup or $\_\_timeGroupAlias, then select a time column from the Column drop-down and a time interval from the Interval drop-down. This generates a time-series query based on your selected time grouping.

Macros

You can enable macros support in the select clause to create time-series queries.

Use the Data operations drop-down to select a macro like $__timeGroup or $__timeGroupAlias. Select a time column from the Column drop-down and a time interval from the Interval drop-down to create a time-series query.

You can also add custom value to the Data operations. For example, a function that’s not in the drop-down list. This allows you to add any number of parameters.

Create a metric query

For backward compatibility, there’s an exception to the above rule for queries that return three columns and include a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below.

To optionally customize the default series name formatting, refer to Standard options definitions.

Example with metric column:

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

Data frame result:

+---------------------+-----------------+
| Name: time          | Name: min       |
| Labels:             | Labels:         |
| Type: []time.Time   | Type: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:05:00 | 3               |
| 2020-01-02 03:10:00 | 6               |
+---------------------+-----------------+

Time series query examples

Use the fill parameter in the $__timeGroupAlias macro to convert null values to be zero instead:

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

Given the data frame result in the following example and using the graph panel, you get two series named value 10.0.1.1 and value 10.0.1.2. To render the series with a name of 10.0.1.1 and 10.0.1.2, use a Standard options definitions display name value of ${__field.labels.hostname}.

Data frame result:

+---------------------+---------------------------+---------------------------+
| Name: time          | Name: value               | Name: value               |
| Labels:             | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
| Type: []time.Time   | Type: []float64           | Type: []float64           |
+---------------------+---------------------------+---------------------------+
| 2020-01-02 03:05:00 | 3                         | 4                         |
| 2020-01-02 03:10:00 | 6                         | 7                         |
+---------------------+---------------------------+---------------------------+

Use multiple columns:

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

Data frame result:

+---------------------+-----------------+-----------------+
| Name: time          | Name: min_value | Name: max_value |
| Labels:             | Labels:         | Labels:         |
| Type: []time.Time   | Type: []float64 | Type: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3               | 4               |
| 2020-01-02 03:05:00 | 6               | 7               |
+---------------------+-----------------+-----------------+

Annotations

You can use Microsoft SQL Server queries as annotation sources to overlay events on your dashboard graphs. For detailed instructions, query examples, and best practices, refer to Microsoft SQL Server annotations.

Use stored procedures

Stored procedures have been verified to work with Grafana queries. However, note that there is no special handling or extended support for stored procedures, so some edge cases may not behave as expected.

Stored procedures can be used in table, time series, and annotation queries, provided that the returned data matches the expected column names and formats described in the relevant previous sections in this document.

Note
Grafana macro functions do not work inside stored procedures.

For the following examples, the database table is defined in Time series queries. Let’s say that we want to visualize four series in a graph panel, such as all combinations of columns valueOne, valueTwo and measurement. Graph panel to the right visualizes what we want to achieve. To solve this, you need to use two queries:

First query:

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value one' as metric,
  avg(valueOne) as valueOne
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

Second query:

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value two' as metric,
  avg(valueTwo) as valueTwo
FROM
  metric_values
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

Stored procedure with epoch time format

You can define a stored procedure to return all the data needed to render multiple series (for example, 4) in a graph panel.

In the following example, the stored procedure accepts two parameters, @from and @to, both of type int. These parameters represent a time range (from/to) in epoch time format and are used to filter the results returned by the procedure.

The query inside the procedure simulates the behavior of $__timeGroup(time, '5m') by grouping timestamps into 5-minute intervals. While the expressions for time grouping are somewhat verbose, they can be extracted into reusable SQL Server functions to simplify the procedure.

CREATE PROCEDURE sp_test_epoch(
  @from int,
  @to 	int
)	AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

Then, in your graph panel, you can use the following query to call the stored procedure with the time range dynamically populated by Grafana:

DECLARE
  @from int = $__unixEpochFrom(),
  @to int = $__unixEpochTo()

EXEC dbo.sp_test_epoch @from, @to

This uses Grafana built-in macros to convert the selected time range into epoch time ($__unixEpochFrom() and $__unixEpochTo()), which are passed to the stored procedure as input parameters.

Stored procedure with `datetime` format

You can define a stored procedure to return all the data needed to render four series in a graph panel.

In the following example, the stored procedure accepts two parameters, @from and @to, of the type datetime. These parameters represent the selected time range and are used to filter the returned data.

The query within the procedure mimics the behavior of $__timeGroup(time, '5m') by grouping data into 5-minute intervals. These expressions can be verbose, but you may extract them into reusable SQL Server functions for improved readability and maintainability.

CREATE PROCEDURE sp_test_datetime(
  @from datetime,
  @to 	datetime
)	AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

To call this stored procedure from a graph panel, use the following query with Grafana built-in macros to populate the time range dynamically:

DECLARE
  @from datetime = $__timeFrom(),
  @to datetime = $__timeTo()

EXEC dbo.sp_test_datetime @from, @to

Next steps

After building your queries, you can:

Use template variables to create dynamic, reusable dashboards
Add annotations to overlay SQL Server events on your graphs
Set up alerting to create alert rules based on your query results
Troubleshoot issues if queries return unexpected results

Microsoft SQL Server template variables

Tue, 18 Aug 2026 10:15:08 +0000

Microsoft SQL Server 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 general information on using variables in Grafana, refer to Add 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 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 [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city]

You can also 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 __text, id __value FROM host

You can also 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 host WHERE region IN ($region)

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
  atimestamp time,
  aint value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp

[[varname]] syntax

Example with a template variable named hostname:

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp

Format variables for SQL queries

When using template variables inside SQL queries, the formatting option you choose determines how Grafana renders the variable value. Choosing the correct format prevents SQL injection risks and avoids broken queries from incorrect quoting.

Use `sqlstring` for safe single-value interpolation

The ${var:sqlstring} format wraps the variable value in single quotes and escapes any internal single quotes. This is the recommended approach for single-value variables used in WHERE clauses:

SELECT * FROM events
WHERE hostname = ${hostname:sqlstring}

If hostname is set to server01, this expands to:

SELECT * FROM events
WHERE hostname = 'server01'

Caution
Don’t manually wrap variables in quotes (for example, '${var}'). Since Grafana v11.3, multi-value variables are automatically quoted when used with the IN operator. Manually adding quotes results in double-quoting (for example, ''value''), which breaks queries.

Multi-value variable formatting

When a variable allows multiple selections, Grafana provides several formatting options:

Format	Syntax	Output for selections `a`, `b`	Use case
Default (auto-quoted)	`$var` or `${var}`	`'a','b'`	`IN` clauses (recommended)
`sqlstring`	`${var:sqlstring}`	`'a'` (single value only)	Equality comparisons
`csv`	`${var:csv}`	`a,b`	Unquoted lists
`singlequote`	`${var:singlequote}`	`'a','b'`	Explicit single-quote wrapping
`doublequote`	`${var:doublequote}`	`"a","b"`	MSSQL identifier quoting
`pipe`	`${var:pipe}`	`a\|b`	Regex patterns
`raw`	`${var:raw}`	`a,b`	No escaping (use with caution)

For multi-value variables in SQL WHERE clauses, the default formatting with IN is typically correct:

SELECT * FROM events
WHERE hostname IN ($hostname)

If hostname has values server01 and server02 selected, this expands to:

SELECT * FROM events
WHERE hostname IN ('server01','server02')

Disable quoting for multi-value variables

To output multi-value variables without automatic quoting, use the csv format:

${servers:csv}

This outputs the values as an unquoted comma-separated list. Use this only when you handle quoting yourself or when the values are numeric.

Refer to Advanced variable format options for the full list of formatting options.

Handle the “All” option in SQL queries

When a variable includes the All option (enabled in variable settings), you need to handle the case where the user selects “All” differently from individual selections.

Pattern: Use a custom “All” value with `LIKE`

Set the Custom all value field in the variable settings to %, then use LIKE in your query:

SELECT * FROM events
WHERE hostname LIKE ${hostname:sqlstring}

When the user selects “All”, hostname resolves to %, and the LIKE '%' matches all rows. When a specific value is selected, LIKE 'server01' matches only that value.

Pattern: Conditional `WHERE` clause with “All”

For IN clauses where % doesn’t work, use a conditional approach. Set the Custom all value to ALL, then write:

SELECT * FROM events
WHERE (
  ${hostname:raw} = 'ALL'
  OR hostname IN ($hostname)
)

When the user selects “All”, the first condition is true and all rows match. When specific values are selected, the IN clause filters normally.

Pattern: Chained variables with “All”

When you have chained (dependent) variables and the parent uses “All”, apply the same pattern. For example, if region feeds into hostname:

Variable query for hostname:

SELECT hostname FROM host
WHERE (${region:raw} = 'ALL' OR region IN ($region))

Panel query:

SELECT $__timeGroupAlias(time, '5m'), COUNT(*) as count
FROM events
WHERE $__timeFilter(time)
  AND (${region:raw} = 'ALL' OR region IN ($region))
  AND (${hostname:raw} = 'ALL' OR hostname IN ($hostname))
GROUP BY $__timeGroup(time, '5m')
ORDER BY 1

Conditional SQL clauses

Grafana doesn’t have built-in support for conditionally omitting entire WHERE clauses based on variable selection. Use one of these patterns to achieve conditional filtering.

Pattern: Always-true condition

Use a condition that evaluates to true when the variable should be ignored:

SELECT * FROM events
WHERE $__timeFilter(time)
  AND (${env:raw} = 'ALL' OR environment IN ($env))
  AND (${sev:raw} = 'ALL' OR severity IN ($sev))

Pattern: CASE expression for optional filters

For more complex scenarios, use a CASE expression:

SELECT * FROM events
WHERE $__timeFilter(time)
  AND 1 = CASE
    WHEN ${hostname:raw} = 'ALL' THEN 1
    WHEN hostname IN ($hostname) THEN 1
    ELSE 0
  END

Known behaviors and limitations

Be aware of the following behaviors when using template variables with Microsoft SQL Server.

Automatic quoting in multi-value variables

Since Grafana v11.3, multi-value variables used with the IN operator are automatically quoted. If you previously wrote WHERE col IN ('${var}') with manual quotes, remove the manual quotes and use WHERE col IN ($var) instead.

Comments inside string literals

The Grafana SQL query parser strips SQL comments (-- and /* */) before macro interpolation. In some cases, -- inside a quoted string literal could be incorrectly interpreted as a comment. If your query contains strings with --, verify the query expands correctly by clicking Generated SQL after running the query.

Variables in alerting queries

Template variables are not supported in alerting queries. Grafana evaluates alert rules on the backend without dashboard context. If your dashboard query uses variables, create a separate alerting query with hard-coded values. For more information, refer to Microsoft SQL Server alerting.

Microsoft SQL Server annotations

Tue, 18 Aug 2026 10:15:08 +0000

Microsoft SQL Server annotations

Annotations overlay event markers on your dashboard visualizations, helping you correlate metric behavior with events like deployments, incidents, or configuration changes. You can use the Microsoft SQL Server data source to create annotation queries that display SQL query results as annotation events.

For general information about annotations, refer to Annotate visualizations.

Before you begin

Before you create MSSQL annotations, ensure you have:

A configured Microsoft SQL Server data source
A table containing event data with at least a time column and a description column
Familiarity with T-SQL query syntax

Create an annotation query

To add a Microsoft SQL Server 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 Microsoft SQL Server data source from the Data source drop-down.
Write an SQL query that returns the required columns.
Click Save dashboard.

Annotation query columns

Your annotation query must return columns with specific names. Grafana uses these names to map query results to annotation fields.

Column	Required	Description
`time`	Yes	The date/time of the event. Can be a native SQL date/time type or a Unix epoch value in seconds.
`timeend`	No	The end time for region annotations. Same format as `time`. Creates a shaded region instead of a line.
`text`	Yes	The event description displayed in the annotation tooltip.
`tags`	No	Comma-separated string used for event tags. Tags help categorize and filter annotations.

Example: Annotation with epoch time

Given a table that stores events with Unix epoch timestamps:

CREATE TABLE [events] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

Query to display events as annotations:

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

The $__unixEpochFilter macro automatically filters events to the dashboard’s selected time range.

Example: Region annotation with start and end times

To display annotations as shaded regions (spanning a duration), include both time and timeend columns:

SELECT
  time_sec as time,
  time_end_sec as timeend,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

Example: Annotation with native `datetime` column

If your table uses native SQL datetime or datetime2 columns instead of epoch values:

SELECT
  time,
  measurement as text,
  convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

The $__timeFilter macro works with native SQL date/time types and filters to the dashboard time range.

Example: Deployment annotations

Display deployment events on your graphs:

SELECT
  deployed_at as time,
  'Deployed ' + version + ' to ' + environment as [text],
  environment as tags
FROM
  [deployments]
WHERE
  $__timeFilter(deployed_at)
ORDER BY 1

Example: Maintenance window annotations

Display maintenance windows as shaded regions:

SELECT
  start_time as time,
  end_time as timeend,
  'Maintenance: ' + description as [text],
  'maintenance' as tags
FROM
  [maintenance_windows]
WHERE
  $__timeFilter(start_time)
ORDER BY 1

Use template variables

You can use template variables in your annotation queries to make them dynamic. For example, filter events by a selected server:

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
  AND server IN ($server)
ORDER BY 1

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`/`datetime2` column.
`$__unixEpochFilter(column)`	Filters by time range using a column with Unix epoch timestamps.

For the full list of available macros, refer to the Microsoft SQL Server query editor.

Best practices

Follow these best practices when creating Microsoft SQL Server 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 at a glance.
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.

Get help

If your annotations aren’t appearing or behaving as expected, refer to Troubleshoot Microsoft SQL Server data source issues for common solutions.

Microsoft SQL Server alerting

Tue, 18 Aug 2026 10:15:08 +0000

Microsoft SQL Server alerting

You can use Grafana Alerting with Microsoft SQL Server to create alerts based on your SQL Server 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 Microsoft SQL Server, ensure you have:

A configured Microsoft SQL Server data source
Appropriate permissions to create alert rules
Understanding of the metrics you want to monitor

Supported query types

Microsoft SQL Server 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 an SQL datetime/datetime2 or a 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 Microsoft SQL Server 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 Microsoft SQL Server:

Navigate to Alerting > Alert rules.
Click New alert rule.
Enter a name for the alert rule.
Select your Microsoft SQL Server data source.
Build your query using the query editor:
- Set the Format to Time series.
- Include a time column using the $__timeGroup() or $__timeGroupAlias() macro.
- Add numeric columns for the values to monitor.
- Use $__timeFilter() to filter data by the evaluation 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 Microsoft SQL Server.

Alert on high error count

Monitor the number of errors over time:

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

Condition: When error_count is above 100.

Alert on average response time

Monitor API response times:

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

Condition: When avg_response_time is above 500 (milliseconds).

Alert on low order volume

Detect drops in order activity:

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

Condition: When order_count is below 10.

Alert on high CPU utilization

Monitor server resource metrics:

SELECT
  $__timeGroupAlias(recorded_at, '5m'),
  AVG(cpu_percent) AS avg_cpu
FROM sys_metrics
WHERE $__timeFilter(recorded_at)
GROUP BY $__timeGroup(recorded_at, '5m')
ORDER BY 1

Condition: When avg_cpu is above 85.

Limitations

When using Microsoft SQL Server 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 aren’t 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 time out 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

Current User authentication not supported

If your data source uses Azure Entra ID Current User authentication, alerting, reporting, and recorded queries are not supported. These features require backend-level credentials that don’t rely on a specific user’s session.

Best practices

Follow these best practices when creating Microsoft SQL Server 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.
Use MSSQL macros: Prefer $__timeGroupAlias() and $__timeGroup() over manual time-bucketing expressions.
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 Microsoft SQL Server data source issues

Tue, 18 Aug 2026 10:15:08 +0000

Troubleshoot Microsoft SQL Server data source issues

This document provides solutions to common issues you may encounter when configuring or using the Microsoft SQL Server (MSSQL) data source in Grafana.

Configuration errors

These errors occur when setting up or accessing the data source configuration in Grafana.

Configuration form not displaying

Symptoms: The data source settings page shows only Delete and Back buttons with no configuration fields.

Cause: The logged-in user has insufficient permissions to configure data sources. Only users with the Organization administrator role (or a custom RBAC role with datasources:write permissions) can access the data source configuration form.

Solution:

Ask an organization administrator to grant you the Organization administrator role, or assign you a custom RBAC role with data source write permissions.
Alternatively, ask an administrator to configure the data source on your behalf or use provisioning to define the data source in YAML.

Connection errors

These errors occur when Grafana cannot establish or maintain a connection to the Microsoft SQL Server.

Unable to connect to the server

Error message: Unable to open tcp connection or dial tcp: connection refused

Cause: Grafana cannot establish a network connection to the SQL Server.

Solution:

Verify that the SQL Server is running and accessible.
Check that the host and port are correct in the data source configuration. The default SQL Server port is 1433.
Ensure there are no firewall rules blocking the connection between Grafana and SQL Server.
Verify that SQL Server is configured to allow remote connections.
For Grafana Cloud, ensure you have configured Private data source connect if your SQL Server instance is not publicly accessible.

Connection timeout

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

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

Solution:

Check the network latency between Grafana and SQL Server.
Verify that SQL Server is not overloaded or experiencing performance issues.
Increase the Connection timeout setting in the data source configuration under Additional settings.
Check if any network devices (load balancers, proxies) are timing out the connection.

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

Cause: There is a mismatch between the encryption settings in Grafana and what the SQL Server supports or requires.

Solution:

For older versions of SQL Server (2008, 2008R2), set the Encrypt option to Disable or False in the data source configuration.
If Encrypt is True, verify that the SQL Server has a valid TLS certificate.
Check that the certificate is trusted by the Grafana server (either in the system CA bundle or specified in TLS/SSL Root Certificate).
If the certificate’s hostname doesn’t match the configured Host value (for example, when using a load balancer or PDC), set Hostname in server certificate to match the certificate’s CN or SAN.
As a temporary workaround for testing, enable Skip TLS Verify (not recommended for production).
Ensure you’re using the latest available service pack for your SQL Server version for optimal compatibility.

TLS handshake failures with FIPS-enabled Grafana

Error message: “TLS handshake failed” or “no cipher suite supported by both client and server”

Cause: Grafana builds using BoringCrypto (FIPS-compliant builds) enforce FIPS 140-3 cipher requirements. SQL Server instances that only support older cipher suites (TLS 1.0, RC4, or 3DES) are incompatible with these builds.

Solution:

Upgrade the SQL Server instance to support TLS 1.2 with FIPS-approved cipher suites (AES-based).
On the SQL Server host, verify TLS 1.2 is enabled in the Windows registry or SQL Server Network Configuration.
If you cannot upgrade SQL Server, use a non-FIPS Grafana build.
Verify which TLS versions your SQL Server supports by checking the SQL Server error log for “TLS handshake” entries.

TLS certificate errors through PDC

Error message: “certificate verify failed” or “x509: certificate signed by unknown authority” when connecting through Private data source connect

Cause: The SQL Server’s TLS certificate must be verifiable from the PDC agent’s perspective, not from Grafana Cloud. If the SQL Server uses a private CA certificate, the PDC agent host must trust that CA.

Solution:

Install the private CA certificate on the PDC agent host’s system trust store.
Alternatively, specify the CA certificate path in the data source’s TLS/SSL Root Certificate field (the path must be accessible from the PDC agent, not from Grafana Cloud).
If the certificate’s hostname doesn’t match what the PDC agent sees, set Hostname in server certificate to the correct value.
Verify the certificate is valid (not expired) from the PDC agent host: openssl s_client -connect <SQL_SERVER_HOST>:1433 -starttls mssql.

Named instance connection issues

Error message: “Cannot connect to named instance” or connection fails when using instance name

Cause: Grafana cannot resolve the SQL Server named instance.

Solution:

Use the format hostname\instancename or hostname\instancename,port in the Host field.
Verify that the SQL Server Browser service is running on the SQL Server machine.
If the Browser service is unavailable, specify the port number directly: hostname,port.
Check that UDP port 1434 is open if using the SQL Server Browser service.

Private data source connect (PDC) errors

These errors occur when using Grafana Cloud with Private data source connect to reach an on-premises or private-network SQL Server.

“No such host” when connecting through PDC

Error message: dial tcp: lookup sqlserver.internal.example.com: no such host

Cause: The PDC agent cannot resolve the SQL Server hostname from its network. This commonly occurs when:

The hostname in the data source configuration is a public DNS name that doesn’t resolve inside the private network.
The PDC agent host doesn’t have access to the internal DNS server.
A cluster or Availability Group Listener DNS entry is misconfigured.

Solution:

In the data source Host field, use the hostname as resolvable from the PDC agent’s network (for example, the internal FQDN or IP address, not a public DNS name).
Verify the PDC agent host can resolve the hostname: run nslookup <SQL_SERVER_HOST> from the agent machine.
If using a cluster or Availability Group Listener, confirm the listener DNS record exists and resolves to the correct IP from the agent’s network.
Check that the PDC agent host has the correct DNS servers configured.

PDC connection breaks after maintenance or IP changes

Cause: The PDC SSH tunnel endpoint IP changed after infrastructure maintenance, breaking the established connection.

Solution:

Restart the PDC agent service to re-establish the SSH tunnel with the updated endpoint.
Verify the PDC agent status shows a healthy connection in Connections > Private data source connect in your Grafana Cloud stack.
If your network uses IP-based firewall rules for outbound traffic, update the allowlist. PDC endpoint IP addresses can change during maintenance windows.
Consider using DNS-based allowlisting instead of IP-based rules where possible to avoid future disruptions.

Credentials not persisting with PDC enabled

Cause: A known issue can cause the data source username to not persist when PDC is enabled.

Solution:

After enabling PDC, save the data source configuration first, then re-enter the username and password and save again.
Click Save & test to verify the credentials are stored and the connection succeeds.
If the issue persists, try disabling PDC, saving credentials, then re-enabling PDC.

Cannot connect to private SQL Server from Grafana Cloud

Cause: Attempting to connect to an on-premises or private-network SQL Server from Grafana Cloud without PDC configured.

Solution:

Grafana Cloud requires Private data source connect (PDC) for any SQL Server that isn’t publicly accessible.
Firewall allowlisting alone doesn’t work because Grafana Cloud data source connections don’t use static IP addresses.
Install and configure a PDC agent on a host in your private network that can reach the SQL Server on port 1433.
Ensure the PDC agent host allows outbound connections on port 22 to the Grafana Cloud PDC endpoint.

For setup instructions, refer to Connect to on-premises SQL Server from Grafana Cloud.

Authentication errors

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

Error message: “Login failed for user ‘username’” or “Authentication failed”

Cause: The authentication credentials are invalid or the user doesn’t have permission to access the database.

Solution:

Verify that the username and password are correct.
Check that the user exists in SQL Server and is enabled.
Ensure the user has access to the specified database.
For Windows Authentication, verify that the credentials are in the correct format (DOMAIN\User).
Check that the SQL Server authentication mode allows the type of login you’re using (SQL Server Authentication, Windows Authentication, or Mixed Mode).

Error message: “Login failed for user ‘’"—the saved username appears blank when Grafana connects to SQL Server.

Cause: A known issue on certain Grafana release channels caused the SQL Server Authentication username to appear saved in the UI but send an empty string to the server during connection. This was identified on the “fast” release channel.

Solution:

Switch to the “steady” release channel if you’re on “fast” and encounter this issue.
After upgrading or switching channels, open the data source configuration, re-enter the username and password, and click Save & test to confirm the credentials are stored correctly.
If the issue persists after re-saving, clear your browser cache and try again.

Connection fails when password contains special characters

Error message: “Login failed for user” or “Connection string parse error” when credentials contain semicolons (;) or closing braces (})

Cause: In Grafana versions prior to v13.0, semicolons and closing braces in usernames or passwords were not properly escaped in the MSSQL connection string, causing authentication failures.

Solution:

Upgrade to Grafana v13.0 or later, which correctly handles these special characters.
If you cannot upgrade, change the SQL Server password to avoid ; and } characters.

Access denied to database

Error message: Cannot open database 'dbname' requested by the login

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 is mapped to the database with appropriate permissions.

Grant at least SELECT permission on the required tables:

USE [your_database]
GRANT SELECT ON dbo.YourTable TO [your_user]

Check that the user doesn’t have any conflicting permissions from the public role.

Windows Authentication (Kerberos) issues

Error message: “Kerberos authentication failed” or “Cannot initialize Kerberos”

Cause: Kerberos configuration is incorrect or incomplete.

Solution:

Verify that the Kerberos configuration file (krb5.conf) path is correct in the data source settings. The default path is /etc/krb5.conf.
For keytab authentication, ensure the keytab file exists and is readable by the Grafana service account.
Check that the realm and KDC settings are correct in the Kerberos configuration.
Verify DNS is correctly resolving the KDC servers.
Ensure the service principal name (SPN) is registered for the SQL Server instance.

Note
Kerberos authentication is not supported in Grafana Cloud. Use SQL Server Authentication or Azure Entra ID instead.

KDC_ERR_C_PRINCIPAL_UNKNOWN with Availability Group Listeners

Error message: “KDC_ERR_C_PRINCIPAL_UNKNOWN” when connecting through a SQL Server Availability Group Listener

Cause: The SPN registered for the SQL Server instance doesn’t match the Availability Group Listener’s DNS name. Kerberos authentication requires an SPN that matches the hostname the client connects to.

Solution:

setspn -S MSSQLSvc/<LISTENER_FQDN>:1433 <DOMAIN>\<SERVICE_ACCOUNT>
setspn -S MSSQLSvc/<LISTENER_FQDN> <DOMAIN>\<SERVICE_ACCOUNT>

Verify the SPN is correctly registered: setspn -L <DOMAIN>\<SERVICE_ACCOUNT>.
Ensure krb5.conf includes the correct realm mapping for the listener’s domain.
If using multiple realms, add cross-realm trust entries to krb5.conf.

Untrusted domain errors with Windows Authentication

Error message: “The login is from an untrusted domain and cannot be used with Windows authentication”

Cause: The Grafana server’s domain isn’t trusted by the SQL Server’s domain, or the Kerberos realm configuration doesn’t map correctly between domains.

Solution:

Verify that a trust relationship exists between the Grafana server’s domain and the SQL Server’s domain.

Check that krb5.conf includes realm mappings for both domains:

[realms]
DOMAIN_A.COM = {
  kdc = kdc1.domain_a.com
}
DOMAIN_B.COM = {
  kdc = kdc1.domain_b.com
}

[domain_realm]
.domain_a.com = DOMAIN_A.COM
.domain_b.com = DOMAIN_B.COM

Ensure the SQL Server service account has delegation permissions if cross-domain access is needed.
As an alternative, use SQL Server Authentication or Azure Entra ID (App Registration), which don’t require domain trust.

Azure Entra ID authentication errors

Error message: “AADSTS error codes” or “Azure AD authentication failed”

Cause: Azure Entra ID (formerly Azure AD) authentication is misconfigured.

Solution:

For App Registration authentication:
- Verify the tenant ID, client ID, and client secret are correct.
- Ensure the app registration has been added as a user in the Azure SQL database.
- Check that the client secret hasn’t expired.
For Managed Identity authentication:
- Verify managed_identity_enabled = true is set in the Grafana server configuration.
- Ensure the managed identity has been added to the Azure SQL database.
- Confirm the Azure resource hosting Grafana has managed identity enabled.
For Current User authentication:
- Ensure user_identity_enabled = true is set in the Grafana server configuration.
- Verify the app registration is configured to issue both Access Tokens and ID Tokens.
- Check that the required API permissions are configured (user_impersonation for Azure SQL).

For detailed Azure authentication configuration, refer to Configure the Microsoft SQL Server data source.

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 rename your date column: $__time(your_date_column).
Verify the time column is of a valid SQL date/time type (datetime, datetime2, 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).
Macros don’t work inside stored procedures—use explicit date parameters instead.
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.

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.

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

SELECT
  your_datetime_column AT TIME ZONE 'Your Local Timezone' AT TIME ZONE 'UTC' AS time,
  value
FROM your_table

Don’t pass timezone parameters to time macros—they’re not supported.

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 TOP clause to limit results: SELECT TOP 1000 ....
Use the $__timeGroup() macro to aggregate data into time intervals.

Stored procedure returns no data

Cause: Stored procedure output isn’t being captured correctly.

Solution:

Ensure the stored procedure uses SELECT statements, not just variable assignments.
Remove SET NOCOUNT ON if present, or ensure it’s followed by a SELECT statement.
Verify the stored procedure parameters are being passed correctly.
Test the stored procedure directly in SQL Server Management Studio with the same parameters.

For more information on using stored procedures, refer to the query editor documentation.

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.
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 in SQL Server Management Studio to identify bottlenecks.

Connection pool exhaustion

Error message: “Too many connections”, “Connection pool exhausted”, or “failed to connect to server”

Cause: Too many concurrent connections to the database. This commonly manifests as intermittent alert failures while dashboards continue to work, because alert evaluations and dashboard queries compete for connections from the same pool.

Solution:

Increase the Max open connection limit in the data source configuration. A value of 50 to 100 handles most deployments with concurrent dashboards and alerts.
Enable Auto max idle to automatically manage idle connections.
Set Max lifetime to 14400 (4 hours) to ensure stale connections are recycled.
Reduce the number of panels querying the same data source simultaneously, or split heavy dashboards into multiple pages.
Check for long-running queries that might be holding connections open (review SQL Server’s sys.dm_exec_sessions).
If alerts fail intermittently but dashboards work, this is a strong indicator of pool exhaustion under concurrent load.

Slow dashboard load with read-only replicas

Symptoms: Dashboards take 5 to 6 minutes to load initially, or queries are significantly slower than expected.

Cause: The data source is configured with ApplicationIntent=ReadOnly in the Host field, which routes all queries to a read-only secondary replica. If the replica is undersized, under-indexed, or experiencing replication lag, queries run much slower than on the primary.

Solution:

Remove ApplicationIntent=ReadOnly from the Host field to route queries back to the primary instance.
If you need to use a read-only replica, ensure it has the same indexes and resources as the primary.
Check the replica’s replication lag and resource utilization (CPU, I/O) during slow periods.
Consider creating a separate data source for replica queries and using it only for specific dashboards that don’t require low latency.

Alert errors

These errors occur when using Microsoft SQL Server queries in Grafana Alerting.

Alerts fail intermittently while dashboards work

Cause: Connection pool exhaustion. Alert evaluations and dashboard queries share the same connection pool. Under concurrent load, alert evaluations may time out waiting for a free connection.

Solution:

Refer to Connection pool exhaustion in the Performance issues section above.

Alert queries return no data

Cause: Alert queries have different requirements than dashboard queries.

Solution:

Ensure the query format is set to Time series (Table format isn’t supported for alerting).
Verify the query doesn’t use template variables (alert queries can’t resolve dashboard variables).
Check that the query returns data within the alert evaluation time range.
Test the query in Explore with a fixed time range to confirm it returns results.

For more information, refer to Microsoft SQL Server alerting.

Template variable errors

These errors occur when using template variables in queries.

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.

Double-quoting breaks queries with multi-value variables

Cause: Since Grafana v11.3, multi-value variables used with IN are automatically quoted. If you manually wrapped the variable in quotes (for example, WHERE col IN ('${var}')), values are now double-quoted (for example, ''value''), causing query failures.

Solution:

Remove manual quotes around the variable: use WHERE col IN ($var) instead of WHERE col IN ('${var}').
For single-value comparisons, use the sqlstring format: WHERE col = ${var:sqlstring}.
Refer to Template variables for formatting options.

Other common issues

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

System databases appear in queries

Cause: Queries accidentally access system databases.

Solution:

The query editor automatically excludes tempdb, model, msdb, and master from the database dropdown.
Always specify the database in your data source configuration to restrict access.
Ensure the database user only has permissions on the intended database.

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.

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 SQL Server logs for additional error details.
Contact Grafana Support if you’re an Enterprise or Cloud customer.

When reporting issues, include:

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

Microsoft SQL Server data source on Grafana Labs

Configure the Microsoft SQL Server data source

Configure the Microsoft SQL Server data source

Before you begin

Add the MSSQL data source

Configure the data source in the UI

Connect to on-premises SQL Server from Grafana Cloud

Azure Entra ID (formerly Azure AD) Authentication

Required server configuration

Current User authentication

App Registration

Managed Identity

Azure Entra Password

Min time interval

Database user permissions

Diagnose connection issues

Provision the data source

Provisioning example

Configure with Terraform

Terraform example

Next steps

Microsoft SQL Server query editor

Microsoft SQL Server query editor

Builder mode

Code mode

Code mode toolbar features

Use autocompletion

Macros

View the interpolated query

Table queries

Time series queries

Macros

Create a metric query

Time series query examples

Annotations

Use stored procedures

Stored procedure with epoch time format

Stored procedure with datetime format

Next steps

Microsoft SQL Server template variables

Microsoft SQL Server template variables

Query variable

Use variables in queries

Format variables for SQL queries

Use sqlstring for safe single-value interpolation

Multi-value variable formatting

Disable quoting for multi-value variables

Handle the “All” option in SQL queries

Pattern: Use a custom “All” value with LIKE

Pattern: Conditional WHERE clause with “All”

Pattern: Chained variables with “All”

Conditional SQL clauses

Pattern: Always-true condition

Pattern: CASE expression for optional filters

Known behaviors and limitations

Automatic quoting in multi-value variables

Comments inside string literals

Variables in alerting queries

Microsoft SQL Server annotations

Microsoft SQL Server annotations

Before you begin

Create an annotation query

Annotation query columns

Example: Annotation with epoch time

Example: Region annotation with start and end times

Example: Annotation with native datetime column

Example: Deployment annotations

Example: Maintenance window annotations

Use template variables

Macros

Best practices

Get help

Microsoft SQL Server alerting

Microsoft SQL Server alerting

Before you begin

Supported query types

Query format requirements

Create an alert rule

Example alert queries

Alert on high error count

Stored procedure with `datetime` format

Use `sqlstring` for safe single-value interpolation

Pattern: Use a custom “All” value with `LIKE`

Pattern: Conditional `WHERE` clause with “All”

Example: Annotation with native `datetime` column