postgres_exporter & Grafana

postgres_exporter scrapes PostgreSQL metrics into Prometheus; Grafana dashboards visualize connections, replication, bloat proxies, and checkpoints. Standardize one dashboard pack per environment and alert on thresholds tied to user pain, not vanity counters.

Recipe

# docker-compose excerpt
services:
  postgres_exporter:
    image: quay.io/prometheuscommunity/postgres-exporter:v0.16.0
    environment:
      DATA_SOURCE_NAME: "postgresql://monitor:secret@db:5432/postgres?sslmode=require"
    ports:
      - "9187:9187"

# prometheus.yml scrape
scrape_configs:
  - job_name: postgresql
    static_configs:
      - targets: ['postgres_exporter:9187']

When to reach for this:

Kubernetes or VM fleet needing unified metrics
Replacing ad-hoc SQL health scripts with continuous scrape
Alertmanager integration for on-call paging

Working Example

Deploy exporter with custom queries and Grafana alerts.

-- Dedicated monitoring role (least privilege)
CREATE ROLE monitor LOGIN PASSWORD 'rotate-me' NOSUPERUSER;
GRANT pg_monitor TO monitor;
GRANT CONNECT ON DATABASE postgres TO monitor;

# queries.yaml custom metric: connection pct
pg_connection_pct:
  query: |
    SELECT round(100.0 * count(*)::numeric /
      (SELECT setting::int FROM pg_settings WHERE name = 'max_connections'), 2) AS pct
    FROM pg_stat_activity
    WHERE backend_type = 'client backend'
  metrics:
    - pct:
        usage: GAUGE
        description: Client connection utilization percent

# alert rule (Prometheus)
groups:
  - name: postgresql
    rules:
      - alert: PostgresConnectionsHigh
        expr: pg_connection_pct > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: PostgreSQL connections above 80%

What this demonstrates:

pg_monitor role for exporter without superuser
Custom query metric for connection saturation
Prometheus alert with for duration to reduce flapping

Deep Dive

Default Metrics Highlights

Metric prefix	Meaning
`pg_stat_database_*`	Commits, rollbacks, deadlocks
`pg_stat_bgwriter_*`	Checkpoint, buffers
`pg_replication_*`	Lag, replay
`pg_locks_count`	Lock mode counts

Grafana Dashboard Layout

Overview row: up, connections %, lag bytes, TPS
Saturation row: disk, WAL rate, checkpoints
Queries row: top from pg_stat_statements exporter sidecar or PMM
Replication row: per-standby lag and slot lag

TLS and RDS

DATA_SOURCE_NAME="postgresql://monitor@rds-host:5432/postgres?sslmode=verify-full&sslrootcert=/etc/rds-ca.pem"

Gotchas

Exporter using superuser - leak risk in metrics labels. Fix: pg_monitor role only.
Scraping primary and standby with same alert rules - standbys have different lag semantics. Fix: instance label and separate dashboards.
Too many custom queries - each adds load. Fix: 5-10 high-value queries, not full pg_stat_statements scrape every 15s.
Alert on pg_up == 0 only - misses degradation. Fix: composite alerts (connections + lag + disk).
Password in DATA_SOURCE_NAME env - visible in process list. Fix: .pgpass file or secrets mount with 0600.
Missing sslmode on managed - auth failures after enabling require SSL. Fix: verify-full with provider CA in container.

Alternatives

Alternative	Use When	Don't Use When
CloudWatch RDS metrics	AWS-only, minimal ops	Custom query metrics needed
Datadog postgres integration	Unified SaaS	Cost at scale
pgwatch2	Opinionated PG dashboards	Already on Prometheus/Grafana
SQL-only cron	Tiny single instance	Growth expected

FAQs

Which exporter image?

prometheuscommunity/postgres-exporter is the maintained community image.

Scrape interval?

15-30s typical. Faster increases load without much gain for capacity metrics.

Multiple databases?

One DSN per target or autodiscover per database with separate scrape jobs.

PgBouncer metrics?

Separate exporter or built-in SHOW STATS parsed by sidecar. Do not double-count with Postgres connections.

Grafana Cloud?

Remote write from Prometheus; same dashboards importable via ID community packs.

High cardinality labels?

Avoid query text as label. Use aggregated metrics only.

Kubernetes ServiceMonitor?

Standard pattern with prometheus-operator; annotate TLS secrets for DSN.

Alert fatigue?

Start with 5 alerts: down, connections 80%, lag, disk 85%, deadlock rate spike.

RDS Enhanced Monitoring?

OS metrics complement exporter; both useful for I/O wait diagnosis.

Test alerts?

Use amtool alert test or Grafana unified alerting test; page staging channel first.

Monitoring Basics - signals to chart
pg_stat_statements - query workload
SLO Dashboards - user-facing panels
Replication Monitoring - lag detail
Monitoring Best Practices - threshold checklist

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.

Recipe

# docker-compose excerpt
services:
  postgres_exporter:
    image: quay.io/prometheuscommunity/postgres-exporter:v0.16.0
    environment:
      DATA_SOURCE_NAME: "postgresql://monitor:secret@db:5432/postgres?sslmode=require"
    ports:
      - "9187:9187"

# prometheus.yml scrape
scrape_configs:
  - job_name: postgresql
    static_configs:
      - targets: ['postgres_exporter:9187']

When to reach for this:

Kubernetes or VM fleet needing unified metrics
Replacing ad-hoc SQL health scripts with continuous scrape
Alertmanager integration for on-call paging

Working Example

Deploy exporter with custom queries and Grafana alerts.

-- Dedicated monitoring role (least privilege)
CREATE ROLE monitor LOGIN PASSWORD 'rotate-me' NOSUPERUSER;
GRANT pg_monitor TO monitor;
GRANT CONNECT ON DATABASE postgres TO monitor;

# queries.yaml custom metric: connection pct
pg_connection_pct:
  query: |
    SELECT round(100.0 * count(*)::numeric /
      (SELECT setting::int FROM pg_settings WHERE name = 'max_connections'), 2) AS pct
    FROM pg_stat_activity
    WHERE backend_type = 'client backend'
  metrics:
    - pct:
        usage: GAUGE
        description: Client connection utilization percent

# alert rule (Prometheus)
groups:
  - name: postgresql
    rules:
      - alert: PostgresConnectionsHigh
        expr: pg_connection_pct > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: PostgreSQL connections above 80%

What this demonstrates:

pg_monitor role for exporter without superuser
Custom query metric for connection saturation
Prometheus alert with for duration to reduce flapping

Deep Dive

Default Metrics Highlights

Metric prefix	Meaning
`pg_stat_database_*`	Commits, rollbacks, deadlocks
`pg_stat_bgwriter_*`	Checkpoint, buffers
`pg_replication_*`	Lag, replay
`pg_locks_count`	Lock mode counts

Grafana Dashboard Layout

Overview row: up, connections %, lag bytes, TPS
Saturation row: disk, WAL rate, checkpoints
Queries row: top from pg_stat_statements exporter sidecar or PMM
Replication row: per-standby lag and slot lag

TLS and RDS

DATA_SOURCE_NAME="postgresql://monitor@rds-host:5432/postgres?sslmode=verify-full&sslrootcert=/etc/rds-ca.pem"

Gotchas

Exporter using superuser - leak risk in metrics labels. Fix: pg_monitor role only.
Scraping primary and standby with same alert rules - standbys have different lag semantics. Fix: instance label and separate dashboards.
Too many custom queries - each adds load. Fix: 5-10 high-value queries, not full pg_stat_statements scrape every 15s.
Alert on pg_up == 0 only - misses degradation. Fix: composite alerts (connections + lag + disk).
Password in DATA_SOURCE_NAME env - visible in process list. Fix: .pgpass file or secrets mount with 0600.
Missing sslmode on managed - auth failures after enabling require SSL. Fix: verify-full with provider CA in container.

Alternatives

Alternative	Use When	Don't Use When
CloudWatch RDS metrics	AWS-only, minimal ops	Custom query metrics needed
Datadog postgres integration	Unified SaaS	Cost at scale
pgwatch2	Opinionated PG dashboards	Already on Prometheus/Grafana
SQL-only cron	Tiny single instance	Growth expected

FAQs

Which exporter image?

prometheuscommunity/postgres-exporter is the maintained community image.

Scrape interval?

15-30s typical. Faster increases load without much gain for capacity metrics.

Multiple databases?

One DSN per target or autodiscover per database with separate scrape jobs.

PgBouncer metrics?

Separate exporter or built-in SHOW STATS parsed by sidecar. Do not double-count with Postgres connections.

Grafana Cloud?

Remote write from Prometheus; same dashboards importable via ID community packs.

High cardinality labels?

Avoid query text as label. Use aggregated metrics only.

Kubernetes ServiceMonitor?

Standard pattern with prometheus-operator; annotate TLS secrets for DSN.

Alert fatigue?

Start with 5 alerts: down, connections 80%, lag, disk 85%, deadlock rate spike.

RDS Enhanced Monitoring?

OS metrics complement exporter; both useful for I/O wait diagnosis.

Test alerts?

Use amtool alert test or Grafana unified alerting test; page staging channel first.

Monitoring Basics - signals to chart
pg_stat_statements - query workload
SLO Dashboards - user-facing panels
Replication Monitoring - lag detail
Monitoring Best Practices - threshold checklist

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.

postgres_exporter & Grafana

Search Documentation

postgres_exporter & Grafana