Specifies the maximum number of pages (as a fraction of total pages in the relation) that VACUUM may scan and fail to set all-frozen in the visibility map before disabling eager scanning.
At a glance
| Property | Value |
|---|---|
| Parameter | vacuum_max_eager_freeze_failure_rate |
| Category | Vacuuming |
| Default | 0.03 |
| Value type | floating point |
| Change scope | Per-session (SET) |
| Available in | PostgreSQL 18, 19 (added in 18) |
What it does
Specifies the maximum number of pages (as a fraction of total pages in the relation) that VACUUM may scan and fail to set all-frozen in the visibility map before disabling eager scanning. A value of 0 disables eager scanning altogether. The default is 0.03 (3%).
Note that when eager scanning is enabled, only freeze failures count against the cap, not successful freezing. Successful page freezes are capped internally at 20% of the all-visible but not all-frozen pages in the relation. Capping successful page freezes helps amortize the overhead across multiple normal vacuums and limits the potential downside of wasted eager freezes of pages that are modified again before the next aggressive vacuum.
(Description quoted from the official PostgreSQL documentation.)
How to apply a change
Can be set per session with SET, per role/database with ALTER ROLE/DATABASE ... SET, or globally in postgresql.conf.
Inspect the current value and source with SHOW vacuum_max_eager_freeze_failure_rate; or SELECT name, setting, unit, context, source FROM pg_settings WHERE name = 'vacuum_max_eager_freeze_failure_rate';.
Tuning guidance
This parameter is rarely a performance lever. Leave it at the default unless you have a specific, documented reason to change it, change it on one session or one role/database first, and confirm the effect with pg_settings and your own measurements before rolling it out cluster-wide.
Reference
PostgreSQL documentation — vacuum_max_eager_freeze_failure_rate.