PostgreSQL Integration

The PostgreSQL collector monitors PostgreSQL database instances, collecting performance metrics, runtime configuration, and reporting connection health. It also detects and reports the PostgreSQL server version (e.g., "PostgreSQL 18.2") via the VersionReporter interface.

Setup

1. Create a monitoring user

Create a dedicated PostgreSQL user with minimal privileges:

CREATE USER proxima_monitor WITH PASSWORD 'your-secure-password';
GRANT pg_monitor TO proxima_monitor;

The pg_monitor role (PostgreSQL 10+) provides read access to statistics views without superuser privileges.

2. Configure the agent

Add a PostgreSQL collector to the agent's config.yaml:

collectors:
  - type: postgresql
    name: pg-main
    dsn: "postgres://proxima_monitor:your-secure-password@localhost:5432/mydb?sslmode=require"

Field	Required	Description
type	Yes	Must be postgresql
name	Yes	Unique name for this collector instance (e.g., pg-main, pg-replica)
dsn	Yes	PostgreSQL connection string

You can monitor multiple PostgreSQL instances by adding multiple collectors with different names:

collectors:
  - type: postgresql
    name: pg-primary
    dsn: "postgres://monitor:pass@primary:5432/app?sslmode=require"
  - type: postgresql
    name: pg-replica
    dsn: "postgres://monitor:pass@replica:5432/app?sslmode=require"

3. Configure via environment variable

For a single PostgreSQL instance, set the PROXIMA_PG_DSN environment variable — the agent normalizes it into one postgresql collector:

export PROXIMA_PG_DSN='postgres://monitor:pass@localhost:5432/mydb?sslmode=require'

For multiple instances, use the YAML collectors array shown above.

Metrics collected

The PostgreSQL collector reports the following metrics under the pg_ prefix:

Metric	Type	Description
pg_connections_active	Gauge	Number of active connections
pg_connections_idle	Gauge	Number of idle connections
pg_connections_max	Gauge	Maximum allowed connections (max_connections)
pg_blocks_hit_total	Counter	Cumulative buffer-cache block hits
pg_blocks_read_total	Counter	Cumulative blocks read from disk
pg_xact_commit_total	Counter	Cumulative committed transactions
pg_xact_rollback_total	Counter	Cumulative rolled-back transactions
pg_deadlocks_total	Counter	Cumulative deadlock count
pg_replication_lag_seconds	Gauge	Replication lag in seconds (replicas only)
pg_database_size_bytes	Gauge	Total database size in bytes
pg_dead_tuples	Gauge	Total dead tuples across all tables
pg_stat_statements_count	Gauge	Tracked query statements (requires pg_stat_statements)
pg_stat_statements_calls_total	Counter	Total query calls (requires pg_stat_statements)
pg_stat_statements_time_seconds_total	Counter	Total query execution time (requires pg_stat_statements)
pg_stat_statements_slow_queries	Gauge	Statements with mean > 100ms (requires pg_stat_statements)

The pg_stat_statements metrics are optional -- if the extension is not installed, they are silently skipped.

Computed (dashboard) metrics

pg_cache_hit_ratio is not emitted by the collector — the backend derives it from the raw block counters above and exposes it on the dashboard:

Metric	Type	Derived from	Description
pg_cache_hit_ratio	Gauge	rate(pg_blocks_hit_total) / (rate(pg_blocks_hit_total) + rate(pg_blocks_read_total))	Buffer cache hit ratio (0.0–1.0)

Dashboard

The Integration Detail Page for PostgreSQL includes a Metrics tab with a dedicated dashboard:

Summary cards:

• Active Connections — current pg_connections_active
• Cache Hit Ratio — current pg_cache_hit_ratio (0.0–1.0)
• Deadlocks — current pg_deadlocks_total
• Replication Lag — current pg_replication_lag_seconds

Chart groups:

Group	Metrics	Layout	Chart Type
Connections	active, idle, max (overlaid)	Full width	Line
Cache	cache hit ratio	Full width	Area
Transactions	committed, rolled back (rate)	Half width	Area
Deadlocks & Replication	deadlocks (rate, line), replication lag (area)	Half width	Mixed
Database Size	database size bytes	Full width	Area
Query Statistics	calls (rate), mean time (rate)	Half width	Area

Byte-valued metrics (e.g., database size) automatically format as KB/MB/GB in chart tooltips. Counter metrics (transactions, deadlocks) display as rates via derivative calculation.

Version Detection

The collector runs SELECT version() during config collection to detect the PostgreSQL server version (e.g., "PostgreSQL 18.2 on x86_64-pc-linux-gnu..."). The version string is parsed to extract the major.minor version and reported via the VersionReporter interface. The version is displayed as a badge next to the collector name on both the Integration Detail Page and the Host Detail Page (Integrations tab).

Permissions

The collector requires the pg_monitor role, which grants:

• pg_read_all_stats — access to pg_stat_* views
• pg_read_all_settings — access to pg_settings

No write access or superuser privileges are needed.

Troubleshooting

Connection refused

status: error
status_message: "dial tcp 127.0.0.1:5432: connect: connection refused"

• Verify PostgreSQL is running: pg_isready -h localhost
• Check pg_hba.conf allows connections from the agent host
• Verify the DSN host and port are correct

Authentication failed

status: error
status_message: "password authentication failed for user \"proxima_monitor\""

• Verify the username and password in the DSN
• Check pg_hba.conf authentication method for the monitoring user

SSL required

status: error
status_message: "SSL is not enabled on the server"

• Set sslmode=disable in the DSN if SSL is not configured on the server
• Or enable SSL on PostgreSQL and use sslmode=require

Checking status

View the collector status in the Proxima Console UI:

1. Navigate to Integrations → PostgreSQL to see all hosts and their status
2. Click Metrics tab on the integration detail page to view the PostgreSQL dashboard
3. Or go to a specific Host → Integrations tab for per-host status
4. Green = ok, Red = error, Gray = unknown