Return which relations own shared_buffers, aggregated per relation and fork and ranked by buffers held: cached bytes, percent of that fork resident, percent of shared_buffers consumed, dirty buffers, average usagecount and pins.
read-onlyany connectionsweeps replication groupsweeps group
bufferCacheContents([limit])Return which relations own shared_buffers, aggregated per relation and fork and ranked by buffers held: cached bytes, percent of that fork resident, percent of shared_buffers consumed, dirty buffers, average usagecount and pins. Never raw per-buffer rows. Answers which relation is driving checkpoint writeback (pair with checkpointStats), whether the visibility-map fork is resident enough for index-only scans to pay off, and -- on a multi-tenant instance -- which database's working set is displacing the others.
Only buffers belonging to this database and the shared catalogs can be resolved to names; buffers held by other databases on the same instance are visible to PostgreSQL but deliberately not reported here. Cost is O(shared_buffers) and does not vary with the limit or with anything else asked: pg_buffercache materialises one row per buffer before any filter applies, so narrowing the question does not narrow the scan. Around 0.5s per 16GB of shared_buffers, and it is subject to the connection's statement_timeout like every other call. bufferCacheSummary reads the same memory through a function that returns one row and is roughly a hundred times cheaper, so prefer it for anything routine.
Requires the pg_buffercache extension and a role with pg_monitor.
Also accepts connection, replication_group, group, role, described once under arguments every tool takes.
Keyed by schema-qualified relation name; each value is its buffered pages and usage counts. An absent extension or a missing grant is reported as {error, hint} in place of the map.
This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. The counters here are each server's own, so members of a replication group legitimately disagree and the answer is their sum, not the primary's copy.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "bufferCacheContents",
"arguments": {
"limit": 2
}
}
}{
"shop.orders": {
"kind": "table",
"buffers": 402211,
"percent_of_shared_buffers": 19.2,
"percent_of_relation": 17.1,
"usage_count_avg": 4.2
},
"shop.orders_pkey": {
"kind": "index",
"buffers": 3300,
"percent_of_shared_buffers": 0.2,
"percent_of_relation": 100.0,
"usage_count_avg": 5.0
}
}Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.
diskUsage, databaseSize, serverSettings, currentActivity, currentLocks, databaseStats, statementStats, wraparoundStatus, progressStats, ioStats, checkpointStats, tableIOStats, hostCapacity, bufferCacheSummary