Skip to main content
HealOps uses PostgreSQL diagnostics to investigate database-related alerts — checking server health, surfacing slow queries, monitoring replication status, and analyzing table statistics.

Prerequisites

  • PostgreSQL 10+ (12+ recommended for full pg_stat_statements support)
  • Network access from the HealOps environment to your PostgreSQL instance
  • A read-only user with access to system views

Setup

Option 1: Interactive CLI

Select PostgreSQL when prompted and provide your host, database, and credentials.

Option 2: Environment variables

Add to your .env:

Option 3: Persistent store

Integrations are automatically persisted to ~/.config/healops/integrations.json:

Creating a read-only user

pg_monitor (available in PostgreSQL 10+) grants read access to all monitoring views including pg_stat_activity, pg_stat_replication, and pg_stat_statements without superuser privileges.

Enabling slow query tracking

Slow query analysis requires the pg_stat_statements extension. Add to postgresql.conf:
Then restart PostgreSQL and run:

Investigation tools

When HealOps investigates a PostgreSQL-related alert, five diagnostic tools are available:

Server status

Retrieves version, uptime, connection counts (total, active, idle, max), transaction commit/rollback rates, and buffer cache hit ratio per database. Useful for spotting connection saturation or cache efficiency drops.

Current queries

Lists active queries running longer than a configurable threshold (default 1 s), excluding the monitoring connection itself. Includes PID, user, client address, duration, wait event, and a truncated query string.

Replication status

Uses pg_is_in_recovery() to reliably detect replica vs primary. On a primary, reports WAL position and per-replica lag (write, flush, replay). Returns a note if the server is a replica or if no replicas are connected.

Slow queries

Reads pg_stat_statements to surface queries with the highest mean execution time. Results include call count, total/mean/min/max execution time (in ms with sub-millisecond precision), rows returned, and buffer cache hit percentage.
Slow query data requires the pg_stat_statements extension to be installed and loaded via shared_preload_libraries. HealOps returns an informative message if the extension is not available.

Table statistics

Reads pg_stat_user_tables and pg_class for a given schema (default public). Returns insert/update/delete/live/dead tuple counts, sequential vs index scan ratios, last vacuum/analyze timestamps, and table sizes in bytes and MB.

Verify

Expected output:

Troubleshooting

Security best practices

  • Use a dedicated read-only user with pg_monitor — avoid superuser credentials for monitoring.
  • Enable SSL (POSTGRESQL_SSL_MODE=require) in production environments.
  • Use scram-sha-256 authentication in pg_hba.conf rather than md5.
  • Store credentials in .env, never in source code.
  • Rotate credentials periodically.