Monitor PostgreSQL with Grafana

Monitor PostgreSQL with Grafana through a defined metrics pipeline, scoped exporter access, actionable alerts and a synthetic incident acceptance exercise.

Last updated

In short

  • A SQL datasource and a metrics exporter serve different purposes.
  • Pin exporter collectors and dashboard queries to actual emitted metrics.
  • Alert delivery and missing-data behavior need an incident drill.
On this page (7)

Integrations · Part of Grafana

Choose the monitoring path before importing a dashboard

Grafana can query PostgreSQL directly through its SQL datasource, or visualize time-series metrics collected through an exporter and monitoring backend. A dashboard built for one path does not automatically work with the other. Start with the operational questions you need to answer, then choose the collection path.

This is a reference monitoring design and incident exercise, not a measured deployment. Prometheus and the PostgreSQL exporter are additional dependencies in the reference topology; their mention here does not establish that they are included in a particular Pilae service package. Confirm that scope separately.

Separate business queries from operational metrics

Path Suitable use Main caution
Grafana PostgreSQL datasource Approved SQL views and current database information Dashboard users can exercise the datasource credential’s capabilities
PostgreSQL exporter to metrics backend Historical operational counters and alerting Collector versions and labels must match dashboard queries
Host/storage monitoring Disk, memory and infrastructure availability Database metrics alone do not show every host failure
Backup-system monitoring Backup age and restore evidence A healthy database does not prove recoverability

Grafana’s PostgreSQL datasource guide documents the built-in connector. For an exporter path, consult the actual postgres_exporter repository, including supported PostgreSQL versions, collectors and connection configuration.

Pin Grafana, exporter, metrics backend and PostgreSQL releases. Record enabled collectors, scrape interval and retention. A community dashboard may assume metrics or labels that your exporter does not emit; inspect the live synthetic environment before relying on its panels.

Use a scoped monitoring identity

The exporter should authenticate with a dedicated monitoring role. Determine which PostgreSQL monitoring permissions are required by the selected collectors and version. Do not solve a missing metric by automatically granting superuser access.

Credential Intended capability Must not imply
Exporter database role Read required statistics Modify business tables
Metrics scraper Read exporter endpoint Reach database administration ports
Grafana datasource credential Query the metrics backend or approved SQL views Administer the monitoring platform
Alert integration token Deliver to intended incident destination Read unrelated messages or change organization settings

Restrict exporter endpoints to the monitoring network. Metrics and labels can reveal database names, usernames, query fragments or operational topology. Review custom collectors and logs for sensitive content. Avoid putting arbitrary SQL text or high-cardinality identifiers into metric labels.

Select a small set of operational signals

PostgreSQL’s statistics documentation explains activity, replication, archiving and database counters. Translate those concepts into the exact metrics available in your chosen exporter rather than inventing names from a dashboard screenshot.

Operational question Signal category Response owner
Can the database be reached? Exporter collection success plus independent service probe Database operator
Is connection capacity nearly exhausted? Active and total connections against configured budget Application and database owners
Are transactions blocked? Locks and long-running transaction observations Database operator
Is recovery exposure growing? Archive failures, archive age and backup status Recovery owner
Is a replica falling behind? Replication progress and lag interpretation Database operator
Is storage approaching exhaustion? Host/storage free space and WAL growth Infrastructure owner

Choose thresholds from the workload and response time required, not from universal numbers. A connection count meaningful for a small application may be harmless for a larger pool. Long-running transactions can affect vacuum and storage even when CPU looks normal.

Make missing data an explicit state

A flat graph can mean a quiet workload, a stopped exporter or an unreachable monitoring backend. Define separate alert behavior for no data, collection failure and an actual database threshold breach. Test each path.

For a synthetic incident, block the exporter’s database connection in a pilot environment. Verify that the collection-failure alert reaches the intended destination, includes the affected instance and links to a useful runbook. Restore connectivity and confirm the alert resolves. Then test a controlled long-running query or connection-pressure scenario without touching production workloads.

Record detection time, notification delivery, acknowledgement and recovery evidence. Those observed values belong to the tested configuration; they should not be turned into a general service-level promise.

Preserve monitoring during recovery

Back up dashboard definitions, alert rules, datasource configuration and the Grafana application database as appropriate to the deployment. Preserve the metrics backend configuration and retention policy separately. Keep secret references recoverable without committing tokens to dashboard JSON or provisioning files.

A database outage may also affect monitoring if both depend on the same host or identity service. Decide which alerts must survive that failure domain and provide an independent path where required. Test notification delivery while the monitored database is unavailable.

Upgrade with a metric contract

Before upgrading the exporter or database, compare enabled collectors and emitted metric names in a staging environment. Run representative dashboard queries and check for empty panels, changed units and altered label cardinality. Keep the previous reviewed dashboard and alert definitions available for rollback.

Acceptance requires more than populated graphs: the monitoring role cannot write business data, the important failure states produce actionable alerts, missing data is distinguishable from health and a restored monitoring stack retains its configuration. Those checks make the dashboard useful to an operator during an incident.

Sources and further reading

Use the linked documentation to confirm the version, edition and contract that apply to your project.

Set up database monitoring

Bring database versions, recovery objectives, current monitoring tools and the incident destination that must receive alerts.