Skip to main content
The database collector gathers metrics about individual databases in your PostgreSQL instance, including disk space usage and connection limits.
This collector is enabled by default.

​
What It Monitors

The database collector queries the pg_database system catalog to retrieve:
  • Database size in bytes
  • Connection limits per database
  • List of all databases (excluding those in the exclude list)

​
Metrics Exposed

​
pg_database_size_bytes

Disk space used by each database in bytes. Type: Gauge
Labels:
  • datname - Database name
Example: 
pg_database_size_bytes{datname="myapp"} 1048576000

​
pg_database_connection_limit

Connection limit set for each database. A value of -1 indicates no limit. Type: Gauge
Labels:
  • datname - Database name
Example: 
pg_database_connection_limit{datname="myapp"} 100

​
SQL Queries Used

The collector executes the following queries: 
-- Get database list and connection limits
SELECT pg_database.datname, pg_database.datconnlimit 
FROM pg_database;

-- Get database size for each database
SELECT pg_database_size($1);

​
Configuration

​
Enable/Disable the Collector

# Disable the database collector
postgres_exporter --no-collector.database

# Explicitly enable it (default behavior)
postgres_exporter --collector.database

​
Exclude Databases

You can exclude specific databases from metrics collection: 
postgres_exporter --exclude-databases=template0,template1
The exclusion filter is applied in the collector code, not in the SQL query, to avoid complex parameterized queries.

​
Use Cases

​
Monitor Database Growth

Track database size over time to plan capacity: 
rate(pg_database_size_bytes{datname="myapp"}[1d])

​
Alert on Connection Limit Approaching

Create alerts when active connections approach the database limit: 
pg_stat_database_numbackends / pg_database_connection_limit > 0.8

​
Identify Largest Databases

Find which databases consume the most disk space: 
topk(5, pg_database_size_bytes)

​
Permissions Required

The database collector requires:
  • CONNECT privilege on the PostgreSQL instance
  • Access to the pg_database system catalog (granted by default)
  • For PostgreSQL 10+: No special permissions needed
  • For PostgreSQL <10: Read access to system catalogs

​
Performance Considerations

The collector queries each database individually using pg_database_size(), which:
  • Is generally fast for small to medium databases
  • May take longer for very large databases (100GB+)
  • Does not lock tables or interfere with normal operations
  • Can be excluded from collection if causing performance issues

Build docs developers (and LLMs) love

Get started for freeTalk to us