bufferCacheSummary

Return how much of shared_buffers is used, dirty and pinned, with the usage-count histogram from pg_buffercache.

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

bufferCacheSummary()

Description

Return how much of shared_buffers is used, dirty and pinned, with the usage-count histogram from pg_buffercache. Cheap enough for a routine health sweep beside checkpointStats. tableIOStats counts only what shared_buffers served, so a miss there may still have come from the OS page cache at RAM speed; this is the only in-core view of that split. Read the histogram rather than a hit ratio: mass at usage_count 2-5 is a stable working set, everything at 0-1 with no unused buffers is clock-sweep churn, and those are the same ratio with opposite diagnoses.

One sample is weak evidence -- two samples minutes apart are the method. The readings cover the whole instance, not this database alone. Requires the pg_buffercache extension at version 1.4 or later, and a role with pg_monitor.

Parameters

None of its own.

Also accepts connection, replication_group, group, role, described once under arguments every tool takes.

Output

Shared buffer occupancy across the instance. An absent extension or a missing grant is reported as {error, hint} instead.

Scope

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.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bufferCacheSummary",
    "arguments": {}
  }
}

Result

{
  "buffers_used": 2011204,
  "buffers_unused": 85948,
  "buffers_dirty": 1204,
  "buffers_pinned": 12,
  "usagecount_avg": 3.1,
  "shared_buffers_blocks": 2097152,
  "block_size_bytes": 8192,
  "shared_buffers_bytes": 17179869184,
  "usage_counts": [
    {
      "usage_count": 5,
      "buffers": 1102233,
      "dirty": 402,
      "pinned": 4
    }
  ]
}

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.