stats_fetch_consistency

Definition PG 18 manual

Determines the behavior when cumulative statistics are accessed multiple times within a transaction. When set to none, each access re-fetches counters from shared memory. When set to cache, the first access to statistics for an object caches those statistics until the end of the transaction unless pg_stat_clear_snapshot() is called. When set to snapshot, the first statistics access caches all statistics accessible in the current database, until the end of the transaction unless pg_stat_clear_snapshot() is called. Changing this parameter in a transaction discards the statistics snapshot. The default is cache.

How it works

stats_fetch_consistency defines repeat-read behavior for cumulative statistics within one transaction. none refetches each object, cache retains each object after first access, and snapshot materializes all accessible database statistics on first access.

The cache or snapshot lasts until transaction end or pg_stat_clear_snapshot(). Changing the setting inside a transaction discards the current statistics snapshot.

none is efficient for monitoring queries that read each counter once; cache gives stable repeated object reads; snapshot gives a coherent interactive view at higher cost, especially with many objects. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Enabling or enlarging stats_fetch_consistency without measuring collection and observation overhead.

Confusing collection semantics with a performance-control or I/O-control setting.

Assuming all statistics are immediately current inside a long transaction.

Collecting sensitive query text or identifiers without matching access and retention policy.

Workload guidance

OLAP: Large catalogs make snapshot expensive; choose stats_fetch_consistency from the monitoring query's access pattern rather than workload label.

OLTP: Use cache for ordinary SQL, none for scrape queries that read each statistic once, and snapshot only for a deliberate coherent inspection. Do not hold a monitoring transaction open indefinitely.

SMALL: Keep cache unless a simple one-pass collector benefits from none. The setting changes read semantics, not collection accuracy.