# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `enum` | Upstream pg_settings type |
| Context | `user` | Settable by an ordinary user |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | `none`, `cache`, `snapshot` | — for non-enum types |
| Category | Statistics / Cumulative Query and Index Statistics | Upstream classification |
| Latest boot value | `cache` | cache |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG15 |
| Present in | PG15–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`5891c7a8ed8f`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5891c7a8ed8f2d3d577e7eea34dacff12d7b6bbd) — pgstat: store statistics in shared memory. |
| Commit date | 2022-04-06 |
| Discussion | [thread 1](https://postgr.es/m/20220303021600.hs34ghqcw6zcokdh@alap3.anarazel.de) · [thread 2](https://postgr.es/m/20220308205351.2xcn6k4x5yivcxyd@alap3.anarazel.de) · [thread 3](https://postgr.es/m/20210319235115.y3wz7hpnnrshdyv6@alap3.anarazel.de) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG15–19 Beta 3 | `cache` | — | cache |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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 | — | — |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`track_counts`](/parameters/track-counts/) · [`track_activities`](/parameters/track-activities/) · [`track_io_timing`](/parameters/track-io-timing/) · [`track_functions`](/parameters/track-functions/)

## References {#references}

- [PostgreSQL 19 Beta 3 — stats_fetch_consistency](https://www.postgresql.org/docs/19/runtime-config-statistics.html#GUC-STATS-FETCH-CONSISTENCY)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)