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.

{{< admonition type="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. {{< /admonition >}}

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:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type PostgreSQL in the search bar.
4. Select the PostgreSQL data source.
5. 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:

Connection section:

{{< admonition type="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. {{< /admonition >}}

Authentication section:

TLS/SSL mode reference

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

{{< admonition type="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. {{< /admonition >}}

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:

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

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

PostgreSQL Options:

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.

Private data source connect:

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:

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:

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.