PostgreSQL data source on Grafana Labs

Configure the PostgreSQL data source

Tue, 23 Jun 2026 13:06:40 +0000

Configure the PostgreSQL data source

This document explains how to configure the PostgreSQL data source and lists all configuration options. For general information on managing data sources, refer to Data source management.

Before you begin

You need the Organization administrator role to configure the data source. You can also configure it via YAML using Grafana provisioning or using Terraform.
Grafana includes a built-in PostgreSQL data source; no plugin installation is required.
Have your PostgreSQL security details ready (certificates and client keys, if using TLS/SSL).
Note your PostgreSQL version; you’ll be prompted for it during configuration.

Note
When adding a data source, the database user you specify should have only SELECT permissions on the relevant schemas and tables. Grafana does not validate the safety of queries, so users could run potentially harmful SQL (for example, DROP TABLE). Create a dedicated PostgreSQL user with restricted permissions to limit risk.

Example:

CREATE USER grafanareader WITH PASSWORD 'password';
GRANT USAGE ON SCHEMA schema TO grafanareader;
GRANT SELECT ON schema.table TO grafanareader;

Replace schema and table with your schema and table names.

Add the PostgreSQL data source

Complete the following steps to set up a new PostgreSQL data source:

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

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

PostgreSQL configuration options

Following is a list of PostgreSQL configuration options:

Setting	Description
Name	Sets the name you use to refer to the data source in panels and queries. Examples: `PostgreSQL-DB-1`.
Default	Toggle to set this specific PostgreSQL data source as the default pre-selected data source in panels and visualizations.

Connection section:

Note
Grafana Cloud users: Grafana Cloud can’t reach databases on localhost, 127.0.0.1, or private IP ranges (10.x, 172.16.x, 192.168.x) directly. If your PostgreSQL instance isn’t publicly accessible, you must set up Private data source connect (PDC) to establish a secure tunnel between Grafana Cloud and your private network. If you experience intermittent connection drops with the Docker-based PDC agent, try switching to the binary-based agent instead.

If your database is publicly accessible but protected by a firewall, you must allowlist the Grafana Cloud outbound IP addresses. Grafana Cloud doesn’t provide per-stack static IP addresses—only service-level IP ranges. For the current list of outbound IP addresses, refer to Allow Grafana Cloud IP addresses in a firewall.

Setting	Description
Host URL	The IP address/hostname and optional port of your PostgreSQL instance. The default PostgreSQL port is `5432`. For IPv6 addresses, use the format `[::1]:5432`. To connect through a Unix socket, enter the socket directory path (for example, `/var/run/postgresql`).
Database name	The name of your PostgreSQL database. This database is used as the default for queries in the query editor.

Authentication section:

Setting	Description
Username	Enter the username used to connect to your PostgreSQL database.
Password	Enter the password used to connect to the PostgreSQL database. This field is optional. If left empty, the PostgreSQL client driver resolves the password using the standard PostgreSQL password file (`.pgpass`). To use a non-default password file location, set the `PGPASSFILE` environment variable in the Grafana server process.
TLS/SSL Mode	Determines whether and how a secure TLS/SSL connection is negotiated with the server. Refer to the TLS/SSL mode reference for guidance on each mode. When set to `disable`, the TLS/SSL Method and Auth Details options aren’t visible.
TLS/SSL Method	Determines how TLS/SSL certificates are configured.
- File system path	This option allows you to configure certificates by specifying paths to existing certificates on the local file system where Grafana is running. Ensure this file is readable by the user executing the Grafana process.
- Certificate content	This option allows you to configure certificates by specifying their content. The content is stored and encrypted in the Grafana database. When connecting to the database, the certificates are saved as files, on the local filesystem, in the Grafana data path.

TLS/SSL mode reference

Choose the TLS/SSL mode based on your security requirements and where your database is hosted:

Mode	Encryption	Server identity verified	When to use
`disable`	No	No	Local development or trusted private networks only. Don’t use in production.
`require`	Yes	No	Recommended minimum for cloud-hosted databases such as Amazon RDS, Azure Database for PostgreSQL, and Google Cloud SQL. Encrypts the connection but doesn’t verify the server’s certificate.
`verify-ca`	Yes	CA only	Use when you need to confirm the server certificate is signed by a trusted CA but don’t need to verify the hostname.
`verify-full`	Yes	CA + hostname	Most secure option. Verifies both the CA and that the server hostname matches the certificate. Recommended for production when you control the certificates.

Note
Most cloud-hosted PostgreSQL services (Amazon RDS, Azure Database for PostgreSQL, Google Cloud SQL) require at minimum require mode. If you leave TLS/SSL Mode set to disable, the connection may be rejected by the server. Check your cloud provider’s documentation for the recommended sslmode setting.

TLS/SSL Auth Details:

If you select the TLS/SSL Mode options require, verify-ca or verify-full and file system path the following are required:

Setting	Description
TLS/SSL Root Certificate	Specify the path to the root certificate file.
TLS/SSL Client Certificate	Specify the path to the client certificate and ensure the file is accessible to the user running the Grafana process.
TLS/SSL Client Key	Specify the path to the client key file and ensure the file is accessible to the user running the Grafana process.

If you select the TLS/SSL Mode option require and TLS/SSL Method certificate content the following are required:

Setting	Description
TLS/SSL Client Certificate	Provide the client certificate.
TLS/SSL Client Key	Provide the client key.

If you select the TLS/SSL Mode options verify-ca or verify-full with the TLS/SSL Method certificate content the following are required:

Setting	Description
TLS/SSL Client Certificate	Provide the client certificate.
TLS/SSL Root Certificate	Provide the root certificate.
TLS/SSL Client Key	Provide the client key.

PostgreSQL Options:

Setting	Description
Version	The PostgreSQL server version. Determines which functions are available in the query builder. The default is 9.3. When you save the data source, Grafana auto-detects the server version and updates this field if it can connect successfully.
Min time interval	Defines a lower limit for the auto group by time interval. Grafana recommends aligning this setting with the data write frequency. For example, set it to `1m` if your data is written every minute. Refer to Min time interval for format examples.
TimescaleDB	A time-series database built as a PostgreSQL extension. When enabled, Grafana uses `time_bucket` in the `$__timeGroup` macro and displays TimescaleDB-specific aggregate functions in the query builder. Grafana auto-detects TimescaleDB on save if your server is version 9.6 or later and the extension is installed. For more information, refer to TimescaleDB documentation.

Connection limits:

These settings control how Grafana manages connections to your PostgreSQL server. Tune these values if you share the database with other applications or use connection pooling software such as PgBouncer.

Setting	Description
Max open	The maximum number of open connections to the database. The default is `100`. Reduce this if your PostgreSQL server has a low `max_connections` limit or if multiple Grafana instances connect to the same database.
Auto max idle	Toggle to set the maximum number of idle connections to the number of maximum open connections. This setting is toggled on by default.
Max idle	The maximum number of connections in the idle connection pool. The default is `100`. When using PgBouncer or similar connection pooling software, consider lowering this to avoid holding unnecessary connections.
Max lifetime	The maximum amount of time in seconds a connection may be reused. The default is `14400` (4 hours). Set a lower value if your network or security policy requires periodic reconnection.

Private data source connect:

Setting	Description
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, refer to Private data source connect (PDC).

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

Secure SOCKS proxy:

If your Grafana instance has the Secure SOCKS proxy feature enabled, a toggle appears in the data source settings. When enabled, Grafana routes PostgreSQL connections through a SOCKS proxy for secure access to databases in private networks. For more information, refer to Configure a Secure SOCKS5 proxy.

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

Min time interval

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

This option can also be configured or overridden in the dashboard panel under the data source settings.

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

Provision the data source

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

Basic provisioning example

The following example provisions a PostgreSQL data source with password authentication and SSL disabled:

apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable' # disable/require/verify-ca/verify-full
      maxOpenConns: 100
      maxIdleConns: 100
      maxIdleConnsAuto: true
      connMaxLifetime: 14400
      postgresVersion: 903 # 903=9.3, 904=9.4, 905=9.5, 906=9.6, 1000=10
      timescaledb: false

Provisioning with TLS

The following example provisions a PostgreSQL data source with verify-full TLS mode using file system paths for certificates:

apiVersion: 1

datasources:
  - name: Postgres-TLS
    type: postgres
    url: db.example.com:5432
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: grafana
      sslmode: 'verify-full'
      tlsConfigurationMethod: 'file-path'
      sslRootCertFile: '/etc/grafana/certs/root.crt'
      sslCertFile: '/etc/grafana/certs/client.crt'
      sslKeyFile: '/etc/grafana/certs/client.key'

Replace <PASSWORD> with your database password and update the certificate paths to match your environment.

Provisioning with TimescaleDB

The following example enables TimescaleDB support:

apiVersion: 1

datasources:
  - name: Postgres-TimescaleDB
    type: postgres
    url: timescale.example.com:5432
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: metrics
      sslmode: 'require'
      postgresVersion: 1000
      timescaledb: true

Replace <PASSWORD> with your database password.

Provisioning with a Unix socket

The following example connects through a Unix socket instead of TCP:

apiVersion: 1

datasources:
  - name: Postgres-Socket
    type: postgres
    url: /var/run/postgresql
    user: grafana
    secureJsonData:
      password: '<PASSWORD>'
    jsonData:
      database: grafana
      sslmode: 'disable'

Replace <PASSWORD> with your database password. When using a Unix socket, set url to the socket directory path. Don’t include a port number.

Provisioning with environment variables

You can use the $__env{} syntax to reference environment variables in provisioning files. This avoids storing credentials in plain text YAML:

apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: $__env{PG_HOST}:$__env{PG_PORT}
    user: $__env{PG_USER}
    secureJsonData:
      password: $__env{PG_PASSWORD}
    jsonData:
      database: $__env{PG_DATABASE}
      sslmode: 'require'

Provisioning configuration reference

The following table lists all jsonData and secureJsonData fields supported when provisioning the PostgreSQL data source:

Field	Location	Description
`database`	`jsonData`	The database name.
`sslmode`	`jsonData`	TLS/SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`.
`maxOpenConns`	`jsonData`	Maximum open connections. Default: `100`.
`maxIdleConns`	`jsonData`	Maximum idle connections. Default: `100`.
`maxIdleConnsAuto`	`jsonData`	Set max idle to max open automatically. Default: `true`.
`connMaxLifetime`	`jsonData`	Connection max lifetime in seconds. Default: `14400`.
`postgresVersion`	`jsonData`	Server version code: `903` (9.3), `904` (9.4), `905` (9.5), `906` (9.6), `1000` (10+).
`timescaledb`	`jsonData`	Enable TimescaleDB support. Default: `false`.
`tlsConfigurationMethod`	`jsonData`	TLS cert method: `file-path` or `file-content`.
`sslRootCertFile`	`jsonData`	Path to root CA certificate (when using `file-path` method).
`sslCertFile`	`jsonData`	Path to client certificate (when using `file-path` method).
`sslKeyFile`	`jsonData`	Path to client key (when using `file-path` method).
`password`	`secureJsonData`	Database password.
`tlsCACert`	`secureJsonData`	Root CA certificate content (when using `file-content` method).
`tlsClientCert`	`secureJsonData`	Client certificate content (when using `file-content` method).
`tlsClientKey`	`secureJsonData`	Client key content (when using `file-content` method).

Troubleshoot provisioning issues

If you encounter metric request errors or other issues when provisioning, refer to Provisioning errors in the PostgreSQL troubleshooting guide.

Configure with Terraform

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

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

Terraform example

The following example creates a basic PostgreSQL data source:

resource "grafana_data_source" "postgres" {
  name = "Postgres"
  type = "postgres"
  url  = "localhost:5432"
  user = "grafana"

  json_data_encoded = jsonencode({
    database         = "grafana"
    sslmode          = "disable"
    maxOpenConns     = 100
    maxIdleConns     = 100
    maxIdleConnsAuto = true
    connMaxLifetime  = 14400
    postgresVersion  = 903
    timescaledb      = 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 PostgreSQL data source, you can:

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

PostgreSQL query editor

Tue, 23 Jun 2026 13:06:40 +0000

PostgreSQL query editor

The PostgreSQL query editor lets you build and run queries against your data source. For general query editor and data transformation concepts, refer to Query and transform data.

You can open the PostgreSQL query editor from the Explore page or from a dashboard panel—click the ellipsis in the upper right of the panel and select Edit.

Note
A default database must be configured in the data source settings. If none is set, or it is removed, the data source will not run queries until a database is configured again.

PostgreSQL query editor components

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

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

PostgreSQL Builder mode

The following components will help you build a PostgreSQL query:

Format - Select the query result format from the drop-down. The default is Table. If you use the Time series format option, one of the columns must be time. Refer to Time series queries for more information.
Table - Select a table from the drop-down. Tables correspond to the chosen database.
Data operations - Optional Select an aggregation from the drop-down. You can add multiple data operations by clicking the + sign. Click the X sign to remove data operations.
Column - Select a column on which to run the aggregation.
Alias - Optional Add an alias from the drop-down. You can also add your own alias by typing it in the box and clicking Enter. Remove an alias by clicking the X.
Filter - Toggle to add filters.
Filter by column value - Optional If you toggle Filter, you can add a column to filter by from the drop-down. To filter on more columns, click the + sign to the right of the condition drop-down. Choose an operator from the drop-down next to the condition. When multiple filters are added, you can add an AND operator to display all true conditions or an OR operator to display any true conditions. Use the second drop-down to choose a filter value. To remove a filter, click the X next to that filter’s drop-down. After selecting a date-type column, you can choose Macros from the operators list and select timeFilter to add the $__timeFilter macro to the query with the selected date column.
Group - Toggle to add Group by column.
Group by column - Select a column to group by from the drop-down. Click the + sign to group by multiple columns. Click the X to remove a column.
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.

PostgreSQL Code mode

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

Note
If a table or column name is a reserved word or contains mixed case or special characters, use double quotes in SQL. For example, "user" or "Created At".

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

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

Macros

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

Grafana expands macros into native PostgreSQL SQL before executing the query. When the TimescaleDB extension is enabled, $__timeGroup and $__timeGroupAlias use time_bucket() for more efficient grouping.

Time-series macros

Macro example	Description
`$__time(dateColumn)`	Renames the column to `time`. Example: `dateColumn AS "time"`. Use for native date/time columns.
`$__timeEpoch(dateColumn)`	Converts to UNIX epoch (seconds) and renames the column to `time`. Example: `extract(epoch from dateColumn) as "time"`. Requires a column argument.
`$__timeFilter(dateColumn)`	Replaces the value with a time range filter using the specified column name. Example: `dateColumn BETWEEN '2020-07-13T20:19:09.254Z' AND '2020-07-13T21:19:09.254Z'`.
`$__timeFrom()`	Replaces the value with the start of the currently active time selection (RFC3339Nano). Example: `'2020-07-13T20:19:09.254Z'`.
`$__timeTo()`	Replaces the value with the end of the currently active time selection (RFC3339Nano). Example: `'2020-07-13T20:19:09.254Z'`.
`$__timeGroup(dateColumn,'5m')`	Replaces the value with an expression suitable for use in a `GROUP BY` clause. Example: `floor(extract(epoch from dateColumn)/300)*300`. With TimescaleDB: `time_bucket('300s', dateColumn)`.
`$__timeGroup(dateColumn,'5m', 0)`	Same as `$__timeGroup(dateColumn,'5m')`, but includes a fill parameter to ensure missing points in the series are added by Grafana, using `0` as the default value. Fill only applies to time series queries.
`$__timeGroup(dateColumn,'5m', NULL)`	Same as `$__timeGroup(dateColumn,'5m', 0)` but `NULL` is used as the value for missing points. Fill only applies to time series queries.
`$__timeGroup(dateColumn,'5m', previous)`	Same as `$__timeGroup(dateColumn,'5m', 0)` but uses the previous value in the series as the fill value. If no previous value exists, it uses `NULL`. Fill only applies to time series queries.
`$__timeGroupAlias(dateColumn,'5m')`	Same as `$__timeGroup` but with an added column alias `AS "time"`. With TimescaleDB, uses `time_bucket()`.

UNIX epoch macros

Macro example	Description
`$__unixEpochFilter(dateColumn)`	Replaces the value with a time range filter for columns storing UNIX epoch (seconds). Example: `dateColumn >= 1494410783 AND dateColumn <= 1494497183`.
`$__unixEpochFrom()`	Replaces the value with the start of the currently active time selection as a UNIX timestamp (seconds). Example: `1494410783`.
`$__unixEpochTo()`	Replaces the value with the end of the currently active time selection as a UNIX timestamp (seconds). Example: `1494497183`.
`$__unixEpochNanoFilter(dateColumn)`	Replaces the value with a time range filter for columns storing UNIX epoch in nanoseconds. Example: `dateColumn >= 1494410783152415214 AND dateColumn <= 1494497183142514872`.
`$__unixEpochNanoFrom()`	Replaces the value with the start of the currently active time selection as a nanosecond timestamp. Example: `1494410783152415214`.
`$__unixEpochNanoTo()`	Replaces the value with the end of the currently active time selection as a nanosecond timestamp. Example: `1494497183142514872`.
`$__unixEpochGroup(dateColumn,'5m', [fillmode])`	Same as `$__timeGroup` but for columns storing UNIX epoch (seconds). Example: `floor((dateColumn)/300)*300`. `fillMode` only applies to time series queries.
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`	Same as `$__unixEpochGroup` but with an added column alias `AS "time"`. `fillMode` only applies to time series queries.

Interval variables

In addition to the macros listed, the following Grafana interval variables are replaced before query execution:

Variable	Description
`$__interval`	Replaced with the calculated interval based on the time range and panel width (for example, `5m`). Use in `$__timeGroup` or directly in custom expressions.
`$__interval_ms`	Same as `$__interval` but in milliseconds (for example, `300000`).

You can set a lower bound for these variables with the Min time interval option in the data source configuration or the panel’s query options.

Macro behavior

Keep the following behavior in mind when using macros:

Comment stripping: Grafana strips SQL comments (-- line comments and /* */ block comments) before expanding macros. Macros placed inside comments aren’t expanded.
TimescaleDB mode: When the TimescaleDB toggle is enabled in the data source configuration, $__timeGroup and $__timeGroupAlias use PostgreSQL’s time_bucket() function instead of floor(extract(epoch ...)).
Trailing comma pattern: A $__timeGroup(...) call followed immediately by a comma (,) is automatically treated as $__timeGroupAlias(...), adding the AS "time" alias. This is a legacy convenience—use $__timeGroupAlias explicitly for clarity.
Inspect expanded SQL: To view the final SQL after macro expansion, open the Query inspector in a panel and check the query that was sent to the database.

Table queries

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

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

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

You can use template variables in queries to create dynamic, reusable dashboards. For example, to filter by a variable named hostname:

SELECT
  $__time("time_date_time"),
  value_double AS value,
  hostname
FROM test_data
WHERE
  $__timeFilter("time_date_time")
  AND hostname IN($hostname)
ORDER BY time

For more information on creating and using template variables with PostgreSQL, refer to PostgreSQL template variables.

Table query with time range columns

Table format queries support a timeend column in addition to the time column. When both are present, Grafana treats the row as a time range rather than a single point. This is useful for displaying events with duration, such as maintenance windows or deployments.

SELECT
  start_time AS "time",
  end_time AS "timeend",
  description,
  status
FROM maintenance_windows
WHERE $__timeFilter(start_time)

Time series queries

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

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

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

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

Time series query results are returned in wide data frame format. In the data frame query result, any column, except for time or string-type columns, transforms into value fields. String columns become field labels.

Metric column detection

The PostgreSQL plugin identifies string-type columns (text, varchar, char, bpchar) as label columns that split the result into multiple series. Numeric and time columns become value fields.

Note
For backward compatibility, an exception to this rule applies to queries that return three columns, one of which is a string column named metric. Instead of converting the metric column into field labels, it’s used as the field name, while the series name is set to its value. Refer to the following example.

Fill missing time series points

When using $__timeGroup or $__unixEpochGroup with a fill parameter (the third argument), Grafana fills gaps in your time series data. This is useful when your data has irregular intervals or missing data points. Fill only works with time series format queries.

The available fill modes are:

Fill mode	Behavior
`0` (or any number)	Missing points are filled with the specified numeric value.
`NULL`	Missing points are filled with `NULL`, which creates gaps in line charts.
`previous`	Missing points use the last known value. If no previous value exists, `NULL` is used.

For example, $__timeGroupAlias("CreatedAt",'5m', 0) groups data into 5-minute intervals and fills any gaps with 0.

Row limits

Grafana applies a server-side row limit to query results to protect against excessive memory usage. If your query returns more rows than the limit, the result is truncated. To reduce the number of rows returned, narrow the dashboard time range, increase the $__timeGroup interval, or add a LIMIT clause to your query.

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 time

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               |
+---------------------+-----------------+

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

Following are time series query examples.

Example with no grouping (raw points):

To return raw time and value points without grouping, use $__time to alias your date/time column as time:

SELECT
  $__time("time_date_time"),
  "value_double" as value
FROM test_data
WHERE $__timeFilter("time_date_time")
ORDER BY time

Example using the fill parameter in the $__timeGroupAlias macro to convert null values to zero:

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

Based on the data frame result in the following example, the time series panel will generate two series named value 10.0.1.1 and value 10.0.1.2. To display the series names as 10.0.1.1 and 10.0.1.2, use the Standard options definitions display value ${__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                         |
+---------------------+---------------------------+---------------------------+

Example with 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 time

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               |
+---------------------+-----------------+-----------------+

Example with UNIX epoch time column:

When your time column stores UNIX epoch (seconds), use $__timeEpoch to alias it as time and $__unixEpochFilter in the WHERE clause:

SELECT
  $__timeEpoch(epoch_seconds_column),
  value_column as value
FROM my_table
WHERE $__unixEpochFilter(epoch_seconds_column)
ORDER BY time

For grouped time series with epoch columns, use $__unixEpochGroupAlias and $__unixEpochFilter. Refer to the Macros table for details.

EXPLAIN queries

You can run EXPLAIN and EXPLAIN ANALYZE queries in Code mode to inspect query execution plans. The results are returned as a table, which is useful for diagnosing slow queries directly within Grafana.

EXPLAIN ANALYZE
SELECT
  $__timeGroupAlias("time_date_time", '5m'),
  avg("value_double") AS value
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Grafana macros are expanded before the query runs, so you can use $__timeFilter and other macros in your EXPLAIN queries to see the actual execution plan for the dashboard’s time range. Set the Format to Table to display the plan output.

Next steps

Use template variables to create dynamic, reusable dashboards.
Add annotations from PostgreSQL to overlay events on your panels.
Set up alerting to get notified when metrics cross thresholds (time series format only).
Troubleshoot issues if you encounter problems with queries.

PostgreSQL template variables

Tue, 23 Jun 2026 13:06:40 +0000

PostgreSQL template variables

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

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

Query variable

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

The PostgreSQL data source includes a dedicated variable query editor with the full SQL editor (Code mode with auto-completion and syntax highlighting) and Value Field / Text Field drop-downs. After you write and run a query, the editor automatically detects the returned columns and populates the field drop-downs so you can map which column provides the variable value and which provides the display label.

To create a query variable:

Navigate to Dashboard settings > Variables.
Click Add variable.
Select Query as the variable type.
Select your PostgreSQL data source.
Write a SQL query in the editor. Macros like $__timeFilter are supported.
Optionally set Value Field and Text Field to control which columns map to the variable value and display label.

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

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

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

Key/value variables

You can create a key/value variable so the drop-down shows a user-friendly label (for example, hostname) while panel queries use a different value (for example, ID). Use the variable editor’s Value field and Text field at the bottom of the query section to specify which query columns supply the value and the label. Your query can use any column names; you do not need __value or __text in the SQL.

Example: run a query that returns hostname and id, then set Text field to hostname and Value field to id.

SELECT hostname, id FROM host

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

Alternatively, you can use the legacy approach: return columns named __text and __value in your query (for example, SELECT hostname AS __text, id AS __value FROM host).

Nested variables

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

SELECT hostname FROM host WHERE region IN($region)

Filter results with `__searchFilter`

Using __searchFilter in the query field filters the query results based on user input in the drop-down selection box. If nothing is entered, the default value for __searchFilter is %.

You must enclose the __searchFilter expression in quotes because Grafana doesn’t add them automatically.

The following example enables real-time searching for hostname as the user types in the drop-down selection box:

SELECT hostname FROM host WHERE hostname LIKE '$__searchFilter'

For tables with a large number of rows, combine __searchFilter with LIMIT to keep the drop-down responsive:

SELECT DISTINCT hostname
FROM host
WHERE hostname LIKE '$__searchFilter'
ORDER BY hostname
LIMIT 100

Regex variable

You can use a Regex type variable to filter or transform values from another variable. For example, if you have a variable named server that returns values like web-prod-01, web-staging-01, and db-prod-01, you can create a regular expression variable to extract only the environment:

Create a new variable with Type: Query.
Set the query to return the raw values.
In the Regex field, enter a pattern to extract or filter. For example, /^web-(.+)-\d+$/ extracts prod and staging from web server names.

You can also use regular expression to filter a variable’s options. For example, setting the Regex field to /prod/ on a variable that returns all server names limits the drop-down to only production servers.

Multi-property variables

The PostgreSQL data source supports multi-property variables. Use them when the same logical concept has different identifiers in different contexts (for example, an environment called dev in one system and development in another). Instead of maintaining several variables in sync, you can map all of those values to one variable and reference the property you need in each panel or query.

You can create a multi-property variable with either Type: Custom or Type: Query:

Type: Custom – In Custom options > JSON, paste your own JSON array with the mapping. Each object in the array can have any number of properties; use text and value for the label and value shown in the drop-down, and add additional properties as needed. For the JSON format and examples, refer to Multi-property custom variables in Add and manage variables.
Type: Query – Write a SQL query that returns multiple columns. In the variable editor, set Value field and Text field to the columns that supply the value and the label for the drop-down. Add one column per property you want to reference; each column name becomes a property name. In panels and queries, reference a property with ${varName.columnName}.

Example (Type: Query): A variable named env that lists environments with different identifiers per cloud. In the variable editor, set Text field to name and Value field to id.

SELECT
  name,
  id,
  aws_identifier AS env_aws,
  azure_identifier AS env_azure
FROM environments

In a panel query you might use $env.env_aws for an AWS-related query and $env.env_azure for an Azure-related query. For more on the concept, refer to Configure multi-property variables in Add and manage variables.

Use variables in queries

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

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 AS time,
  aint AS value
FROM table
WHERE $__timeFilter(atimestamp) AND hostname IN($hostname)
ORDER BY atimestamp ASC

[[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 ASC

Multi-value variable with IN clause

When a variable has Multi-value enabled, Grafana automatically adds quotes around each selected value. For example, if the user selects web01 and web02, $hostname expands to 'web01','web02'. Use the IN operator to match:

SELECT
  $__timeGroupAlias("created_at", '5m'),
  count(*) AS requests
FROM access_log
WHERE $__timeFilter("created_at")
  AND hostname IN($hostname)
GROUP BY time
ORDER BY time

If only a single value is selected, the IN clause still works correctly—IN('web01') is equivalent to = 'web01'.

Multi-value variable with numeric columns

For numeric columns (such as IDs), disable quoting with the csv format option so values aren’t wrapped in quotes:

SELECT name FROM host WHERE id IN(${host_id:csv})

If host_id has values 1, 2, and 3 selected, this expands to IN(1,2,3) instead of IN('1','2','3').

Disable quoting for multi-value variables

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

${servers:csv}

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

Refer to Advanced variable format options for additional information.

PostgreSQL annotations

Tue, 23 Jun 2026 13:06:40 +0000

PostgreSQL annotations

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

For general information about annotations, refer to Annotate visualizations.

Before you begin

Before creating PostgreSQL annotations, ensure you have:

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

Create an annotation query

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

Query columns

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

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

Example queries

The following examples show common annotation query patterns.

Basic annotation with epoch time

Display events using UNIX epoch timestamps:

SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

Range annotation with start and end time

Display events with duration as shaded regions:

SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

Annotation with native SQL date/time

Display events using native PostgreSQL date/time columns:

SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__timeFilter(native_date_time)

Deployment annotations

Display deployment events:

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

Range annotation for maintenance windows

Display maintenance windows as shaded regions:

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

Macros

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

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

Best practices

Follow these best practices when creating PostgreSQL annotations:

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

PostgreSQL alerting

Tue, 23 Jun 2026 13:06:40 +0000

PostgreSQL alerting

The PostgreSQL data source supports Grafana Alerting. You can create alert rules that evaluate time series queries against your PostgreSQL database and send notifications when conditions are met.

Before you begin

Ensure your PostgreSQL data source is configured.
Familiarize yourself with Alert rules and Create a Grafana-managed alert rule.

Supported query format

Only time series queries can be used in alert rule conditions.

Your query must return a column named time (native SQL date/time or UNIX epoch) and one or more numeric value columns.
Table formatted queries aren’t supported in alert rule conditions.

For details on writing time series queries, refer to Time series queries in the PostgreSQL query editor.

Limitations

Keep the following limitations in mind when using PostgreSQL with Grafana Alerting:

Time series format only: Alert rules require the query Format set to Time series. Table format queries can’t be used as alert conditions.
No fill mode in alerts: The fill parameter in $__timeGroup (for example, $__timeGroup(col, '5m', 0)) isn’t applied during alert evaluation. Missing data points remain as gaps.
Single query per condition: Each alert condition evaluates a single query. If you need to combine results from multiple queries, use math expressions in the alert rule.
Template variables aren’t supported: Alert queries don’t support dashboard template variables because alerts evaluate independently of any dashboard context. Hard-code values or use alert rule labels instead.

Create an alert rule

To create an alert rule that uses PostgreSQL:

Go to Alerting in the left menu and select Alert rules.
Click New alert rule.
In the query section, select your PostgreSQL data source.
Set the query Format to Time series.
Write a SQL query that returns a time column and one or more numeric values.
Configure the condition, evaluation group, and notification settings.
Save the rule.

For step-by-step guidance, refer to Create a Grafana-managed alert rule.

Example queries for alerting

The following examples show common PostgreSQL alerting patterns.

Threshold alert

The following query returns a time series suitable for a threshold alert (for example, alert when average value exceeds a limit):

SELECT
  $__timeGroupAlias("time_date_time", '5m'),
  avg("value_double") AS value
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Use condition types such as Is above or Is below in the alert rule to evaluate the series.

Multi-dimensional alert

To create separate alert instances for each value of a label column, include a string column in your query. Grafana creates one alert instance per unique label value, so you can monitor each host, service, or region independently.

SELECT
  $__timeGroupAlias("time_date_time", '5m'),
  avg("value_double") AS value,
  hostname
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time, hostname
ORDER BY time

This query produces a separate time series for each hostname. The alert rule evaluates the condition against each series independently, so you receive individual notifications per host.

Alert on row count

To alert when the number of rows in a time window exceeds a threshold (for example, error count):

SELECT
  $__timeGroupAlias("created_at", '5m'),
  count(*) AS error_count
FROM error_logs
WHERE $__timeFilter("created_at")
  AND severity = 'ERROR'
GROUP BY time
ORDER BY time

Template annotations and labels

You can use template annotations and labels to include query results or metadata in alert notifications and labels.

Best practices

Follow these best practices when using PostgreSQL for alerting:

Keep queries fast: Alert rules evaluate on a schedule (for example, every minute). Avoid expensive joins, subqueries, or scanning large tables without indexes. Add indexes on time columns and any columns used in WHERE clauses.
Use $__timeFilter: Always include a $__timeFilter or $__unixEpochFilter macro to limit data to the evaluation window. Without it, the query scans the entire table on every evaluation.
Handle NULL values: If your data contains NULL values, Grafana treats them as “no data.” Configure the alert rule’s No data behavior to match your expectations (for example, Alerting, No data, or OK).
Test in Explore first: Verify your query returns the expected time series in Explore before using it in an alert rule. Check the Format is set to Time series and results are sorted by time.
Set realistic evaluation intervals: Choose an evaluation interval that gives your query enough time to complete. If your query takes 10 seconds, don’t evaluate every 10 seconds—allow for headroom.

Troubleshoot PostgreSQL data source issues

Tue, 23 Jun 2026 13:06:40 +0000

Troubleshoot PostgreSQL data source issues

This document provides troubleshooting information for common errors you may encounter when using the PostgreSQL data source in Grafana.

Connection errors

The following errors occur when Grafana cannot establish or maintain a connection to PostgreSQL.

Failed to connect to PostgreSQL

Error message: failed to connect to ... : connect: connection refused or dial tcp: connect: connection refused

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

Solution:

Verify that the Host URL is correct in the data source configuration.
Check that PostgreSQL is running and accessible from the Grafana server.
Verify the port is correct (the PostgreSQL default port is 5432).
Ensure there are no firewall rules blocking the connection.
Check that PostgreSQL is configured to accept connections from the Grafana server in pg_hba.conf.
For Grafana Cloud, ensure you have configured Private data source connect if your PostgreSQL instance is not publicly accessible.

Grafana Cloud can’t reach a private database

Error message: dial tcp: connect: connection refused, i/o timeout, or context deadline exceeded when using Grafana Cloud with a database on a private network.

Cause: Grafana Cloud runs in a hosted environment and can’t directly reach databases on localhost, 127.0.0.1, or private IP ranges (10.x, 172.16.x, 192.168.x). This is the most common issue when migrating from self-hosted Grafana to Grafana Cloud.

Solution:

Set up Private data source connect (PDC) to create a secure tunnel between Grafana Cloud and your private network.
Install the PDC agent on a machine that has network access to your PostgreSQL instance.
If you experience intermittent connection drops with the Docker-based PDC agent, try the binary-based agent instead—this has resolved stability issues in some environments.
Update the Host URL in the data source settings to use the hostname as seen from the PDC agent’s network (not localhost).

Request timed out

Error message: “context deadline exceeded” or “i/o timeout”

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

Solution:

Check the network latency between Grafana and PostgreSQL.
Verify that PostgreSQL is not overloaded or experiencing performance issues.
Increase the Max lifetime setting in the data source configuration under Connection limits.
Reduce the time range or complexity of your query.
Check if any network devices (load balancers, proxies) are timing out the connection.

Host not found

Error message: failed to connect to ... : hostname resolving error or lookup hostname: no such host

Cause: The hostname specified in the data source configuration can’t be resolved.

Solution:

Verify the hostname is spelled correctly.
Check that DNS resolution is working on the Grafana server.
Try using the database’s public IP address instead of a hostname. This is a useful diagnostic step and can serve as a workaround if DNS resolution is the issue.
Ensure the PostgreSQL server is accessible from the Grafana server’s network.
For Grafana Cloud, DNS resolution behavior can differ between stack regions and cloud providers. If a hostname resolves from one stack but not another, try the direct IP address and contact Grafana Support.

Authentication errors

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

No PostgreSQL user name specified

Error message: FATAL: no PostgreSQL user name specified in startup packet (SQLSTATE 28000)

Cause: The connection to PostgreSQL was attempted without a username. This typically means the Username field in the data source configuration is empty or was cleared.

Solution:

Open the data source settings and verify the Username field contains a valid PostgreSQL user.
Click Save & test and confirm the connection succeeds.
If the username disappears after saving, check your Grafana version. A bug in Grafana v13.1 on the fast release channel caused the username field to be cleared on save. Upgrading to a patched release or switching to the steady release channel resolves this issue.

Password authentication failed

Error message: failed to connect to ... : server error: FATAL: password authentication failed for user "username" (SQLSTATE 28P01)

Cause: The username or password is incorrect.

Solution:

Verify that the username and password are correct in the data source configuration.
Check that the user exists in PostgreSQL.
Verify the password has not expired.
If no password is specified, ensure a PostgreSQL password file is configured.

Permission denied

Error message: ERROR: permission denied for table table_name (SQLSTATE 42501) or ERROR: permission denied for schema schema_name (SQLSTATE 42501)

Cause: The database user does not have permission to access the requested table or schema.

Solution:

Verify the user has SELECT permissions on the required tables.

Grant the necessary permissions:

GRANT USAGE ON SCHEMA schema_name TO grafanareader;
GRANT SELECT ON schema_name.table_name TO grafanareader;

Check that the user has access to the correct database.
Verify the search path includes the schema containing your tables.

No pg_hba.conf entry

Error message: failed to connect to ... : server error: FATAL: no pg_hba.conf entry for host "ip_address", user "username", database "database_name" (SQLSTATE 28000)

Cause: PostgreSQL is not configured to accept connections from the Grafana server.

Solution:

Edit the pg_hba.conf file on the PostgreSQL server.
Add an entry to allow connections from the Grafana server:
text
```
host    database_name    username    grafana_ip/32    md5
```
Reload PostgreSQL configuration: SELECT pg_reload_conf();
If using SSL, ensure the correct authentication method is specified (for example, hostssl instead of host).

TLS and certificate errors

The following errors occur when there are issues with TLS configuration.

Certificate verification failed

Error message: “x509: certificate signed by unknown authority” or “certificate verify failed”

Cause: Grafana cannot verify the TLS certificate presented by PostgreSQL.

Solution:

Set the TLS/SSL Mode to the appropriate level (require, verify-ca, or verify-full).
If using a self-signed certificate, add the CA certificate in TLS/SSL Auth Details.
Verify the certificate chain is complete and valid.
Ensure the certificate has not expired.
For testing only, set TLS/SSL Mode to disable (not recommended for production).

SSL not supported

Error message: failed to connect to ... : server refused TLS connection or server does not support SSL

Cause: The PostgreSQL server is not configured for SSL connections, but the data source requires SSL.

Solution:

Set TLS/SSL Mode to disable if SSL is not required.
Alternatively, enable SSL on the PostgreSQL server by configuring ssl = on in postgresql.conf.
Ensure the server has valid SSL certificates configured.

Client certificate error

Error message: “TLS: failed to find any PEM data in certificate input” or “could not load client certificate”

Cause: The client certificate or key is invalid or incorrectly formatted.

Solution:

Verify the certificate and key are in PEM format.
Ensure the certificate file path is correct and readable by the Grafana process.
Check that the certificate and key match (belong to the same key pair).
If using certificate content, ensure you’ve pasted the complete certificate including headers.

Database errors

The following errors occur when there are issues with the database configuration.

Database does not exist

Error message: failed to connect to ... : server error: FATAL: database "database_name" does not exist (SQLSTATE 3D000)

Cause: The specified database name is incorrect or the database doesn’t exist.

Solution:

Verify the database name in the data source configuration.
Check that the database exists: \l in psql or SELECT datname FROM pg_database;
Ensure the database name is case-sensitive and matches exactly.
Verify the user has permission to connect to the database.

Relation does not exist

Error message: ERROR: relation "table_name" does not exist (SQLSTATE 42P01)

Cause: The specified table or view does not exist, or the user cannot access it.

Solution:

Verify the table name is correct and exists in the database.
Check the schema name if the table is not in the public schema.
Use fully qualified names: schema_name.table_name.
Verify the user has SELECT permission on the table.
Check the search path: SHOW search_path;

Query errors

The following errors occur when there are issues with SQL syntax or query execution.

Query truncated by double-dash in string literals

Error message: Unexpected syntax errors or truncated results when string values contain -- (double dash).

Cause: In Grafana versions before 13.1, the SQL comment-stripping parser didn’t correctly handle -- inside single-quoted strings. A query like WHERE name = 'value--suffix' would be truncated at the --, causing the rest of the query to be silently dropped. This also affected strings with consecutive hyphens (for example, '10YDE-VE-------2' would be truncated to '10YDE-VE).

This was fixed in Grafana 13.1 with a quote-aware comment-stripping parser (PR #121772). The fix also handles PostgreSQL dollar-quoted strings ($$...$$).

Solution:

Upgrade to Grafana 13.1 or later, which includes the fix.
If you can’t upgrade immediately, work around the issue by using PostgreSQL string concatenation to avoid literal -- in your queries:
SQL
```
WHERE name = 'value' || '--' || 'suffix'
```
Alternatively, use a parameterized approach with a template variable for the value.

Query syntax error

Error message: ERROR: syntax error at or near "keyword" (SQLSTATE 42601)

Cause: The SQL query contains invalid syntax.

Solution:

Check your query syntax for typos or invalid keywords.
Verify column and table names are correctly quoted if they contain special characters or are reserved words.
Use double quotes for identifiers: "column_name".
Test the query directly in a PostgreSQL client such as psql.

Column does not exist

Error message: ERROR: column "column_name" does not exist (SQLSTATE 42703)

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

Solution:

Verify the column name is spelled correctly.
Check that column names are case-sensitive in PostgreSQL when quoted.
Use the correct quoting for column names: "Column_Name" for case-sensitive names.
Verify the column exists in the table: \d table_name in psql.

No time column found

Error message: “no time column found” or time series visualization shows no data

Cause: The query result does not include a properly formatted time column.

Solution:

Ensure your query includes a column named time that returns a timestamp or epoch value.
Use an alias to rename your time column: SELECT created_at AS time.
Ensure the time column is of type timestamp, timestamptz, or a numeric epoch value.
Order results by the time column: ORDER BY time ASC.

Macro expansion error

Error message: “macro ‘$__timeFilter’ not found” or incorrect query results with macros

Cause: Grafana macros aren’t being properly expanded.

Solution:

Verify the macro syntax is correct, for example $\_\_timeFilter(time_column).
Ensure the column name passed to the macro exists in your table.
Check that the macro isn’t inside a SQL comment (-- or /* */). Grafana strips comments before expanding macros, so macros inside comments are silently ignored.
Use the Preview toggle in Builder mode to see the expanded query.
Open the Query inspector to view the exact SQL sent to PostgreSQL after macro expansion.
For time-based macros, ensure the column contains timestamp data.

Performance issues

The following issues relate to slow query execution or resource constraints.

Query timeout

Error message: “canceling statement due to statement timeout” or “query timeout”

Cause: The query took longer than the configured timeout.

Solution:

Reduce the time range of your query.
Add indexes to columns used in WHERE clauses and joins.
Use the $\_\_timeFilter macro to limit data to the dashboard time range.
Increase the statement timeout in PostgreSQL if you have admin access.
Optimize your query to reduce complexity.

Too many connections

Error message: failed to connect to ... : server error: FATAL: too many connections for role "username" (SQLSTATE 53300) or connection pool exhausted

Cause: The maximum number of connections to PostgreSQL has been reached.

Solution:

Reduce the Max open connections setting in the data source configuration.
Increase max_connections in PostgreSQL’s postgresql.conf if you have admin access.
Check for connection leaks in other applications connecting to the same database.
Enable Auto max idle to automatically manage idle connections.

Slow query performance

Cause: Queries take a long time to execute.

Solution:

Reduce the time range of your query.
Add appropriate indexes to your tables.
Use the $\_\_timeFilter macro to limit the data scanned.
Increase the Min time interval setting to reduce the number of data points.
Use EXPLAIN ANALYZE in PostgreSQL to identify query bottlenecks.
Consider using materialized views for complex aggregations.

Provisioning errors

The following errors occur when provisioning the data source via YAML.

Invalid provisioning configuration

Error message: “metric request error” or data source test fails after provisioning

Cause: The provisioning YAML file contains incorrect configuration.

Solution:

Ensure parameter names match the expected format exactly.
Verify the database name is not included in the URL.
Use the correct format for the URL: hostname:port.
Check that string values are properly quoted in the YAML file.
Refer to the provisioning example for the correct format.

Example correct configuration:

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable'

Other common issues

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

Empty query results

Cause: The query returns no data.

Solution:

Verify the time range includes data in your database.
Check that table and column names are correct.
Test the query directly in PostgreSQL.
Ensure filters are not excluding all data.
Verify the $\_\_timeFilter macro is using the correct time column.

TimescaleDB functions not available

Cause: TimescaleDB-specific functions like time_bucket are not available in the query builder.

Solution:

Enable the TimescaleDB toggle in the data source configuration under PostgreSQL Options.
Verify TimescaleDB is installed and enabled in your PostgreSQL database.
Check that the timescaledb extension is created: CREATE EXTENSION IF NOT EXISTS timescaledb;

Data appears delayed or missing recent points

Cause: The visualization doesn’t show the most recent data.

Solution:

Check the dashboard time range and refresh settings.
Verify the Min time interval is not set too high.
Ensure data has been committed to the database (not in an uncommitted transaction).
Check for clock synchronization issues between Grafana and PostgreSQL.

Get additional help

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

Check the PostgreSQL documentation for database-specific guidance.
Review the Grafana community forums for similar issues.
Contact Grafana Support if you are a Cloud Pro, Cloud Contracted, or Enterprise user.
When reporting issues, include:
- Grafana version
- PostgreSQL version
- Error messages (redact sensitive information)
- Steps to reproduce
- Relevant configuration such as data source settings, TLS mode, and connection limits (redact passwords and other credentials)

PostgreSQL data source on Grafana Labs

Configure the PostgreSQL data source

Configure the PostgreSQL data source

Before you begin

Add the PostgreSQL data source

PostgreSQL configuration options

TLS/SSL mode reference

Min time interval

Provision the data source

Basic provisioning example

Provisioning with TLS

Provisioning with TimescaleDB

Provisioning with a Unix socket

Provisioning with environment variables

Provisioning configuration reference

Troubleshoot provisioning issues

Configure with Terraform

Terraform example

Next steps

PostgreSQL query editor

PostgreSQL query editor

PostgreSQL query editor components

PostgreSQL Builder mode

PostgreSQL Code mode

Macros

Time-series macros

UNIX epoch macros

Interval variables

Macro behavior

Table queries

Table query with time range columns

Time series queries

Metric column detection

Fill missing time series points

Row limits

EXPLAIN queries

Next steps

PostgreSQL template variables

PostgreSQL template variables

Query variable

Key/value variables

Nested variables

Filter results with __searchFilter

Regex variable

Multi-property variables

Use variables in queries

Multi-value variable with IN clause

Multi-value variable with numeric columns

Disable quoting for multi-value variables

PostgreSQL annotations

PostgreSQL annotations

Before you begin

Create an annotation query

Query columns

Example queries

Basic annotation with epoch time

Range annotation with start and end time

Annotation with native SQL date/time

Deployment annotations

Range annotation for maintenance windows

Macros

Best practices

PostgreSQL alerting

PostgreSQL alerting

Before you begin

Supported query format

Limitations

Create an alert rule

Example queries for alerting

Threshold alert

Multi-dimensional alert

Alert on row count

Template annotations and labels

Best practices

Troubleshoot PostgreSQL data source issues

Troubleshoot PostgreSQL data source issues

Connection errors

Failed to connect to PostgreSQL

Grafana Cloud can’t reach a private database

Request timed out

Filter results with `__searchFilter`