PostgreSQL data source on Grafana Labs

Configure the PostgreSQL data source

Fri, 03 Apr 2026 12:35:46 -0500

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:

Setting	Description
Host URL	The IP address/hostname and optional port of your PostgreSQL instance.
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. If a password is not specified and your PostgreSQL is configured to request a password, the data source will look for a standard PostgreSQL password file.
TLS/SSL Mode	Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. When TLS/SSL Mode is disabled, TLS/SSL Method and TLS/SSL Auth Details aren’t visible options.
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 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.
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 to display TimescaleDB-specific aggregate functions in the query builder. For more information, refer to TimescaleDB documentation.

Connection limits:

Setting	Description
Max open	The maximum number of open connections to the database. The default is `100`.
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`.
Max lifetime	The maximum amount of time in seconds a connection may be reused. The default is `14400`, or 4 hours.

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.

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.

PostgreSQL provisioning example

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

Troubleshoot provisioning issues

If you encounter metric request errors or other issues when provisioning, see 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

Fri, 03 Apr 2026 12:35:46 -0500

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, see 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.

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

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"`.
`$__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 the `$__timeGroup(dateColumn,'5m')` macro, but includes a fill parameter to ensure missing points in the series are added by Grafana, using 0 as the default value. This applies only to time series queries.
`$__timeGroup(dateColumn,'5m', NULL)`	Same as the `$__timeGroup(dateColumn,'5m', 0)` but `NULL` is used as the value for missing points. This applies only 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`. This applies only to time series queries.
`$__timeGroupAlias(dateColumn,'5m')`	Same as `$__timeGroup` but with an added column alias `AS "time"`. With TimescaleDB, uses `time_bucket()`.
`$__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 works with time series queries.
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`	Same as `$__unixEpochGroup` but with an added column alias `AS "time"`. `fillMode` only works with time series queries.

Table SQL queries

If the Format option is set to Table, you can execute virtually any type of SQL query. The Table panel will automatically display 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. For example, to filter by a variable named hostname: WHERE hostname IN($hostname).

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, on the other hand, become field labels.

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 is used as the field name, while the series name is set to its value. See the following example for reference.

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. See the Macros table for details.

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

Fri, 03 Apr 2026 12:35:46 -0500

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.

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 allows the query results to be filtered based on the user’s input in the drop-down selection box. If you don’t enter anything, the default value for __searchFilter is %.

Note that you must enclose the __searchFilter expression in quotes as Grafana doesn’t add them automatically.

The following example demonstrates how to use __searchFilter in the query field to enable real-time searching for hostname as the user types in the drop-down selection box.

SELECT hostname FROM host WHERE hostname LIKE '$__searchFilter'

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.

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

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 will be 'server01', 'server02'. To disable quoting, use the csv formatting option for variables:

${servers:csv}

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

Refer to Advanced variable format options for additional information.

PostgreSQL annotations

Fri, 03 Apr 2026 12:35:46 -0500

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

Fri, 03 Apr 2026 12:35:46 -0500

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 are not supported in alert rule conditions.

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

Create an alert rule

To create an alert rule that uses PostgreSQL:

Go to Alerting (bell icon) 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 numeric value(s).
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 time series query for alerting

The following query returns a time series suitable for a threshold alert (e.g. alert when 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.

Template annotations and labels

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

Troubleshoot PostgreSQL data source issues

Fri, 03 Apr 2026 12:35:46 -0500

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.

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 cannot be resolved.

Solution:

Verify the hostname is spelled correctly.
Check that DNS resolution is working on the Grafana server.
Try using an IP address instead of a hostname.
Ensure the PostgreSQL server is accessible from the Grafana server’s network.

Authentication errors

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

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 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 (psql, pgAdmin).

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 are not 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.
Use the Preview toggle in Builder mode to see the expanded query.
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

Min time interval

Provision the data source

PostgreSQL provisioning example

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

Table SQL queries

Time series queries

Next steps

PostgreSQL template variables

PostgreSQL template variables

Query variable

Key/value variables

Nested variables

Filter results with __searchFilter

Multi-property variables

Use variables in queries

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

Create an alert rule

Example time series query for alerting

Template annotations and labels

Troubleshoot PostgreSQL data source issues

Troubleshoot PostgreSQL data source issues

Connection errors

Failed to connect to PostgreSQL

Request timed out

Host not found

Authentication errors

Password authentication failed

Permission denied

No pg_hba.conf entry

TLS and certificate errors

Certificate verification failed

SSL not supported

Client certificate error

Database errors

Database does not exist

Relation does not exist

Query errors

Query syntax error

Column does not exist

No time column found

Macro expansion error

Performance issues

Query timeout

Too many connections

Slow query performance

Provisioning errors

Invalid provisioning configuration

Other common issues

Filter results with `__searchFilter`