stats_fetch_consistency

stats_fetch_consistency — Sets the consistency of accesses to statistics data. Observed in PG15–19 Beta 3; its last measured boot default is cache in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Sets the consistency of accesses to statistics data.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valuenone, cache, snapshot: — for non-enum types
Category , ValueStatistics / Cumulative Query and Index Statistics: Upstream classification
Latest boot value , Valuecache: cache

Lifecycle

Fact	Value
First observed	PG15
Present in	PG15–19 Beta 3
Removed in	No
Introduction commit	`5891c7a8ed8f` — pgstat: store statistics in shared memory.
Commit date	2022-04-06
Discussion	thread 1 · thread 2 · thread 3

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG15–19 Beta 3	`cache`	—	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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
OLAP	Large catalogs make snapshot expensive; choose stats_fetch_consistency from the monitoring query’s access pattern rather than workload label.
Small nodes	Keep cache unless a simple one-pass collector benefits from none. The setting changes read semantics, not collection accuracy.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

track_counts · track_activities · track_io_timing · track_functions