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.
