Optimize data source connections for PDC

When you route data source queries through private data source connect (PDC), a few configuration choices help you avoid connectivity issues and get the most reliable performance. This document covers the key best practices.

Use internal network addresses for data source URLs

When you configure a data source to use PDC, enter the address as it appears on your private network. The PDC agent resolves addresses and establishes connections from within your network, so use the internal hostname or IP address and port rather than a public endpoint.

For example, if your PostgreSQL instance is available at postgres.internal.example.com:5432 or 10.0.1.50:5432 on your private network, use that as the data source URL in Grafana.

Warning
localhost or 127.0.0.1 as the data source URL will resolve to the PDC agent host, not your data source.

Verify data source compatibility

PDC only supports backend data source plugins. Frontend data sources cannot use PDC because the proxy connection runs from the Grafana backend, not the browser.

Before configuring a data source for PDC, verify that it appears in the supported data sources list.

Reduce connection lifetime for connection-pooling data sources

Some data sources maintain persistent database connections (connection pooling) and reuse them across multiple queries. When PDC components restart – for example, during agent updates, Kubernetes rolling updates, or server-side rollouts – the PDC system enters a graceful shutdown period of slightly more than 5 minutes. During this window:

Grafana stops routing new connections through the shutting-down component.
Existing TCP connections that remain open beyond the graceful shutdown period risk interruption mid-query.

If a query runs on a stale connection, it returns an error such as Partial data response error or db query error: invalid connection.

To prevent this, set the Max lifetime field on affected data sources to a value under 300 seconds (5 minutes). This ensures Grafana replaces pooled connections before the graceful shutdown period expires.

Affected data sources

The following data sources use connection pooling and require a reduced Max lifetime value when used with PDC:

Data source	Configuration field	Default	Recommended value
Microsoft SQL Server	`Max lifetime`	`0` (unlimited)	Under 300 seconds
MySQL	`Max lifetime`	`14400` (4 hours)	Under 300 seconds
PostgreSQL	`Max lifetime`	`14400` (4 hours)	Under 300 seconds

You can find the Max lifetime setting under Connection limits in each data source’s configuration page.

Test connectivity before building dashboards

After you configure a data source with PDC, click Save & test on the data source configuration page to verify the connection works through the PDC tunnel. Confirm that queries return data before building dashboards or alerts that depend on the connection.

If the test fails, refer to Troubleshoot PDC for common errors and resolution steps.