data-source/mssql

28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Default Microsoft SQL Server port is 1433

The default SQL Server port is 1433. If SQL Server is running on a non-standard port, specify it in the Host field.

Named instance connection format in Host field

To connect to a SQL Server named instance, use the format hostname\instancename or hostname\instancename,port in the Host field. If the SQL Server Browser service is unavailable, specify the port number directly instead.

SQL Server Browser service on UDP port 1434

SQL Server uses the Browser service on UDP port 1434 to resolve named instances. UDP port 1434 must be open if using the SQL Server Browser service for named instance resolution.

Encryption option for older SQL Server versions

For older versions of SQL Server (2008, 2008R2), set the Encrypt option to Disable or False in the data source configuration to avoid TLS handshake failures.

FIPS-enabled Grafana requires TLS 1.2 with AES-based cipher suites

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. Upgrade SQL Server to support TLS 1.2 with FIPS-approved cipher suites (AES-based).

PDC agent must trust SQL Server TLS certificate

When using Private data source connect, the SQL Server's TLS certificate must be verifiable from the PDC agent's perspective, not from Grafana Cloud. If SQL Server uses a private CA certificate, the PDC agent host must trust that CA. Install the private CA certificate on the PDC agent host's system trust store, or specify the CA certificate path in the data source's TLS/SSL Root Certificate field (the path must be accessible from the PDC agent).

Verify PDC agent DNS resolution with nslookup

To verify the PDC agent host can resolve the SQL Server hostname, run nslookup <SQL_SERVER_HOST> from the agent machine. For clusters or Availability Group Listeners, confirm the listener DNS record exists and resolves to the correct IP from the agent's network.

PDC SSH tunnel uses port 22 for outbound connections

The PDC agent requires outbound connections on port 22 to the Grafana Cloud PDC endpoint. Ensure the PDC agent host allows outbound connections on port 22.

Known issue: SQL Server username appears blank on fast release channel

A known issue on certain Grafana release channels (notably the fast release channel) causes the SQL Server Authentication username to appear saved in the UI but send an empty string to the server during connection, resulting in login failures with an empty username. Switch to the steady release channel, then re-enter and save the credentials.

Special characters in passwords require Grafana v13.0+

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. Upgrade to Grafana v13.0 or later for proper handling, or change the SQL Server password to avoid these characters.

Windows Authentication requires krb5.conf configuration

Kerberos authentication requires verification 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. Verify the realm and KDC settings are correct, DNS correctly resolves KDC servers, and the service principal name (SPN) is registered for the SQL Server instance.

Kerberos not supported in Grafana Cloud

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

Register SPN for SQL Server Availability Group Listener

To resolve KDC_ERR_C_PRINCIPAL_UNKNOWN errors with Availability Group Listeners, register an SPN for the Availability Group Listener DNS name using setspn -S MSSQLSvc/<LISTENER_FQDN>:1433 <DOMAIN>\<SERVICE_ACCOUNT> and setspn -S MSSQLSvc/<LISTENER_FQDN> <DOMAIN>\<SERVICE_ACCOUNT>. Verify the SPN is correctly registered with setspn -L <DOMAIN>\<SERVICE_ACCOUNT>.

krb5.conf realm mapping for untrusted domains

To configure Kerberos for cross-domain authentication, include realm mappings in krb5.conf for both domains. Example configuration: [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

Azure Entra ID App Registration authentication requirements

For Azure Entra ID 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.

Azure Managed Identity requires managed_identity_enabled configuration

For Azure 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.

Azure Entra ID Current User authentication requirements

For Azure Entra ID 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).

Time series queries require named time column

For time series visualization, ensure the query includes a column named time and returns data sorted by the time column using ORDER BY. Use the $__time() macro to rename a date column: $__time(your_date_column). The time column must be of a valid SQL date/time type (datetime, datetime2, date) or contain Unix epoch values.

View expanded SQL with Generated SQL option

To debug macro expansion issues, click Generated SQL after running a query to view the expanded query and see how macros were replaced.

Macros expand to UTC values

Time macros ($__time, $__timeFilter, etc.) always expand to UTC values. If timestamps are stored in local time, convert them to UTC in the query using AT TIME ZONE clauses.

Example: Convert local time to UTC in SQL query

To convert timestamps stored in local time to UTC: SELECT your_datetime_column AT TIME ZONE 'Your Local Timezone' AT TIME ZONE 'UTC' AS time, value FROM your_table

Macros do not work inside stored procedures

Grafana macros do not work inside stored procedures. Use explicit date parameters instead.

Template variable multi-value formatting changed in Grafana v11.3

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. Remove manual quotes: use WHERE col IN ($var) instead of WHERE col IN ('${var}'). For single-value comparisons, use the sqlstring format: WHERE col = ${var:sqlstring}.

SQL permission required for table access

To grant a user SELECT permission on specific tables: USE [your_database] GRANT SELECT ON dbo.YourTable TO [your_user]

Connection pool exhaustion causes intermittent alert failures

When alerts fail intermittently while dashboards work, this indicates 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.

Recommended connection pool settings for concurrent dashboards and alerts

To manage connection pool exhaustion: increase the Max open connection limit in the data source configuration to 50 to 100 for 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.

ApplicationIntent=ReadOnly routes queries to read-only replica

When the data source is configured with ApplicationIntent=ReadOnly in the Host field, all queries are routed 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, potentially causing dashboards to take 5 to 6 minutes to load.

Query editor automatically excludes system databases

The query editor automatically excludes tempdb, model, msdb, and master from the database dropdown.

Give your agent this brain