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

Data sources

Microsoft SQL Server

Configure

Grafana Cloud Enterprise Open source

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.

Before you begin

Grafana comes with a built-in MSSQL data source plugin, eliminating the need to install a plugin.
You must have the Organization administrator role to configure the MSSQL data source. Organization administrators can also configure the data source via YAML with the Grafana provisioning system.
Familiarize yourself with your MSSQL security configuration and gather any necessary security certificates and client keys.
Verify that data from MSSQL is being written to your Grafana instance.

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 (e.g., `ApplicationIntent`) by separating them with semicolons (`;`).
Database	Sets the name of the MSSQL database to connect to.

TLS/SSL Auth:

Encrypt - Determines whether or to which extent a secure SSL TCP/IP connection will be negotiated with the server.

Encrypt Setting	Description
Disable	Data sent between the client and server is not encrypted.
False	The default setting. Only the login packet is encrypted; all other data is sent unencrypted.
True	All data sent between the client and server is encrypted.

Note
If you’re using an older version of Microsoft SQL Server like 2008 and 2008R2, you may need to disable encryption to be able to connect.

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 (e.g., from a prior `kinit` command). No file needed.	- Credential cache path: Path to in-memory credential (e.g., `/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: e.g., `/home/grot/cache.json`

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:

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.

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 your data’s 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 ADS Advanced Settings

Setting	Description	Default
UDP Preference Limit	Defines the maximum packet size (in bytes) that Kerberos libraries will 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`

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) and Configure Grafana private data source connect (PDC) for instructions on setting up a PDC connection.

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

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

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 MySQL 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!'