stat_database collector exposes comprehensive database-level statistics from the PostgreSQL statistics collector.
Status
Default: EnabledMetrics
Connection and Backend Metrics
pg_stat_database_numbackends
Type: GaugeDescription: Number of backends currently connected to this database Labels:
datid, datname
Transaction Metrics
pg_stat_database_xact_commit
Type: CounterDescription: Number of transactions in this database that have been committed Labels:
datid, datname
pg_stat_database_xact_rollback
Type: CounterDescription: Number of transactions in this database that have been rolled back Labels:
datid, datname
Block I/O Metrics
pg_stat_database_blks_read
Type: CounterDescription: Number of disk blocks read in this database Labels:
datid, datname
pg_stat_database_blks_hit
Type: CounterDescription: Number of times disk blocks were found already in the buffer cache Labels:
datid, datname
Tuple (Row) Metrics
pg_stat_database_tup_returned
Type: CounterDescription: Number of rows returned by queries in this database Labels:
datid, datname
pg_stat_database_tup_fetched
Type: CounterDescription: Number of rows fetched by queries in this database Labels:
datid, datname
pg_stat_database_tup_inserted
Type: CounterDescription: Number of rows inserted by queries in this database Labels:
datid, datname
pg_stat_database_tup_updated
Type: CounterDescription: Number of rows updated by queries in this database Labels:
datid, datname
pg_stat_database_tup_deleted
Type: CounterDescription: Number of rows deleted by queries in this database Labels:
datid, datname
Conflict and Error Metrics
pg_stat_database_conflicts
Type: CounterDescription: Number of queries canceled due to conflicts with recovery in this database (standby servers only) Labels:
datid, datname
pg_stat_database_deadlocks
Type: CounterDescription: Number of deadlocks detected in this database Labels:
datid, datname
Temporary File Metrics
pg_stat_database_temp_files
Type: CounterDescription: Number of temporary files created by queries in this database Labels:
datid, datname
pg_stat_database_temp_bytes
Type: CounterDescription: Total amount of data written to temporary files by queries in this database Labels:
datid, datname
I/O Timing Metrics
pg_stat_database_blk_read_time
Type: CounterDescription: Time spent reading data file blocks by backends in this database, in milliseconds Labels:
datid, datname
Note: Requires track_io_timing = on
pg_stat_database_blk_write_time
Type: CounterDescription: Time spent writing data file blocks by backends in this database, in milliseconds Labels:
datid, datname
Note: Requires track_io_timing = on
Activity Time Metrics
pg_stat_database_active_time_seconds_total
Type: CounterDescription: Time spent executing SQL statements in this database, in seconds Labels:
datid, datname
Availability: PostgreSQL 14+
Statistics Reset
pg_stat_database_stats_reset
Type: CounterDescription: Time at which these statistics were last reset (Unix timestamp) Labels:
datid, datname
SQL Query
PostgreSQL 14+:PostgreSQL Versions
Supported: All versions Version-specific columns:- PostgreSQL 14+:
active_timecolumn added
Required Permissions
The monitoring user needs:- Access to
pg_stat_databaseview (granted toPUBLICby default)
Example Output
Use Cases
Cache Hit Ratio
Transaction Rate
Write Activity
Temporary File Usage
Performance Tuning
Low Cache Hit Ratio
Ifblks_hit / (blks_hit + blks_read) < 0.90:
- Increase
shared_buffers - Optimize queries to reduce sequential scans
- Add indexes where appropriate
High Temporary File Usage
Iftemp_files or temp_bytes is high:
- Increase
work_memfor sort and hash operations - Optimize queries to reduce memory usage
- Add indexes to avoid sorts
High Rollback Ratio
If rollbacks are high:- Application logic issues
- Deadlocks or serialization failures
- Connection pool issues