Buffer Cache Hit Rate %, PostgreSQL

​

At a glance

This gauge reports what fraction of PostgreSQL’s page reads were served from its own shared-buffers cache rather than read from disk. It is the share of blks_hit in the total of blks_hit + blks_read. A high number means your working set fits in memory and queries rarely wait on storage; a number sliding below 95% on a production OLTP database is the classic sign that shared_buffers is undersized for your working set, or that a query pattern has started scanning more data than the cache can hold. For a DBA this is one of the cleanest early-warning gauges you have: it bends before latency does, so it gives you a head start on a memory-pressure problem before users feel it.

​

Calculation

hit_rate = blks_hit / (blks_hit + blks_read)
fire when: hit_rate < 0.95  (on a production OLTP profile)

1. Delta, not lifetime. The raw counters in pg_stat_database accumulate from the last stats reset, so the lifetime ratio is dominated by history and barely moves. The card computes the delta between polls, so a fresh problem (a new full-table-scan query, a cold cache after restart) shows up promptly instead of being buried under months of good history.
2. Per-database scope. pg_stat_database reports per database. The card surfaces the active database(s); a rarely-touched database with a poor ratio over a tiny sample is not the same signal as your busy OLTP database dipping.

​

Worked example

1. Disk reads jumped sharply. blks_read per minute roughly tripled while blks_hit per minute fell. Something is now reading pages that are not in the cache, and reading a lot of them.
2. Latency is starting to follow, but has not spiked yet. Cross-reference Query Latency p95 (ms); it has crept from 22ms to 41ms. The hit-rate gauge bent first, which is exactly the head start this card is meant to give.
3. The timing points at the release. The dip starts within minutes of the deploy that added search. The prime suspect is a new query doing a sequential scan over a large table that does not fit comfortably alongside the existing working set in 8 GB of shared buffers.

Drill-down to the offending table:
  SELECT relname,
         heap_blks_hit,
         heap_blks_read,
         round(100.0 * heap_blks_hit
               / nullif(heap_blks_hit + heap_blks_read, 0), 2) AS hit_pct
  FROM pg_statio_user_tables
  ORDER BY heap_blks_read DESC
  LIMIT 5;

  Result: products_search at 71% hit rate, heap_blks_read dominating.
  -> the new search query scans products_search without a usable index,
     pulling cold pages from disk on every request and evicting hot
     catalogue pages, which drags the whole-database ratio down.

Fixes, in order of preference:
  1. Add the missing index so the search query stops sequential-scanning.
     (EXPLAIN (ANALYZE, BUFFERS) on the new query confirms Seq Scan + high reads.)
  2. If the scan is unavoidable, consider whether shared_buffers (8 GB on a
     32 GB host) should grow toward the common 25% guideline, but only after
     confirming the working set genuinely exceeds the current cache.
  3. Check pg_stat_statements for the new query's share of total reads.

1. Hit rate bends before latency breaks. That is the value of this gauge. By the time p95 latency is obviously bad, customers are already affected; a hit-rate dip gives you minutes-to-hours of warning to find the cause.
2. A sudden dip is usually a query, not a capacity wall. When the rate falls right after a change, suspect a new full-table scan thrashing the cache, not a working set that quietly outgrew memory. The table-level drill-down (pg_statio_user_tables) finds it fast.
3. 95% is an OLTP threshold, not a universal law. A reporting or analytics database that deliberately scans large cold datasets will run lower and that is fine. Set the threshold to your workload; do not chase 99% on a database whose job is to read data that will never fit in cache.

​

Sibling cards

​

Reconciling against the source

Compute it directly: SELECT datname, blks_hit, blks_read, round(100.0 * blks_hit / nullif(blks_hit + blks_read, 0), 2) AS hit_pct FROM pg_stat_database WHERE datname = current_database();. Note this is the lifetime ratio since the last reset, not the recent delta the card shows. Drill to the table level with pg_statio_user_tables (heap_blks_hit / heap_blks_read) and to indexes with pg_statio_user_indexes to find the source of a dip. Inspect a specific query with EXPLAIN (ANALYZE, BUFFERS) <query>;; the Buffers: shared hit=... read=... line is the per-query version of this metric. On a managed service, the provider exposes a related metric: RDS / Aurora surface BufferCacheHitRatio, Cloud SQL reports cache-hit ratios in its insights, and Azure exposes a similar buffer-cache metric. These align with the gauge but may be sampled and scoped differently.

​

Known limitations / FAQs

​

Tracked live in Vortex IQ Nerve Centre