PostgreSQL cache and I/O statistics

A PostgreSQL shared-buffer hit means the requested block was already in PostgreSQL's buffer cache. A block read means PostgreSQL had to request it from the operating system, but the operating system may still satisfy that request from its own page cache rather than physical storage.

This read-only query includes raw counts, a calculated ratio, timing availability, temporary-file activity, and the reset timestamp.

SELECT
  datname,
  blks_read,
  blks_hit,
  CASE
    WHEN blks_hit + blks_read > 0
    THEN round(100.0 * blks_hit / (blks_hit + blks_read), 2)
  END AS shared_buffer_hit_percent,
  blk_read_time,
  blk_write_time,
  temp_files,
  temp_bytes,
  stats_reset,
  current_setting('track_io_timing') AS track_io_timing
FROM pg_stat_database
WHERE datname = current_database();

Except for the current backend count exposed elsewhere in this view, database statistics are cumulative. Compare nonnegative deltas between observations with the same stats_reset; a lower counter or changed reset time breaks the comparison.

The stable pg_statio_user_tables view separates heap, index, and TOAST block requests by relation. It does not identify the exact statement responsible.

SELECT
  schemaname,
  relname AS table_name,
  heap_blks_read,
  heap_blks_hit,
  idx_blks_read,
  idx_blks_hit,
  toast_blks_read,
  toast_blks_hit
FROM pg_statio_user_tables
ORDER BY heap_blks_read + idx_blks_read DESC
LIMIT 50;

PostgreSQL 16 and newer expose cluster-wide pg_stat_io rows by backend type, I/O object, and context. The view is unavailable on PostgreSQL 14 and 15, and its columns can evolve across major releases, so use the documentation for the exact server version.

SELECT
  current_setting('server_version_num')::integer AS server_version_num,
  to_regclass('pg_catalog.pg_stat_io') IS NOT NULL AS pg_stat_io_available;

Even pg_stat_io does not cover every I/O path and cannot distinguish storage reads from data already in the kernel page cache. Pair it with operating-system or managed-provider metrics.

Provider architecture can add caches and storage metrics outside PostgreSQL shared buffers. Neon documents a Local File Cache and working-set charts in addition to PostgreSQL shared buffers. Supabase exposes platform I/O reporting and PostgreSQL inspection tools. Compare like-for-like measurements instead of treating a core hit ratio as the provider's entire cache path.

• A lower hit ratio is not automatically a memory shortage; large sequential reads may be expected.
• A high hit ratio does not prove queries are fast or the system has no I/O bottleneck.
• blks_read is not a provider disk-IOPS or billing counter.
• Cumulative lifetime ratios can hide a recent change; compare compatible deltas.
• Resetting statistics for a cleaner measurement destroys existing context and can affect maintenance decisions.

Connected telemetry captures database-wide block hits, block reads, temporary bytes, and the reset timestamp, and presents the buffer-cache ratio as cumulative rather than disk latency. Query telemetry and the pg_stat_statements analyzer can separately rank fingerprint-level shared-block and temporary-block counters.

DatabaseMeter does not currently collect pg_stat_io, operating-system I/O, or every provider cache metric. Use provider-native monitoring to confirm CPU, storage latency, IOPS, and architecture-specific cache behavior.