Parameter · Vacuuming / Freezing
vacuum_max_eager_freeze_failure_rate
Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning. A value of 0.0 disables eager scanning and a value of 1.0 will eagerly scan up to 100 percent of the all-visible pages in the relation. If vacuum successfully freezes these pages, the cap is lower than 100 percent, because the goal is to amortize page freezing across multiple vacuums.
- Default:
0.03 - Type: real
- Range: 0 … 1
- Applies: Session (any user)
In plain words
New in PostgreSQL 18. A normal vacuum now also visits some pages that are already "all-visible" and tries to freeze them early, spreading freezing work over time instead of one huge aggressive vacuum later. If too many such attempts fail (rows still too young), it gives up for that part of the table. 0 turns eager scanning off.
For DBAs and operators
Details from PostgreSQL 18:
- Only normal vacuums scan eagerly; aggressive vacuums already read every unfrozen page.
- The table is handled in regions of 4096 blocks. In each region, eager scanning stops after
rate × 4096pages failed to become all-frozen (default 3% = 122 pages). - Successes are capped at 20% of the all-visible-but-not-all-frozen pages for the whole table; then eager scanning is disabled for this vacuum (disabling eager scanning after freezing 1234 eagerly scanned blocks of relation "app.public.orders", at INFO in VERBOSE, DEBUG2 otherwise).
- Can be set per table:
ALTER TABLE t SET (vacuum_max_eager_freeze_failure_rate = 0.1).
Observe the effect in VACUUM VERBOSE / autovacuum logs: pages: … scanned (x% of total), N eagerly scanned, the frozen: line, and pg_class.relallfrozen (new in 18). Raise it for big append-mostly tables to keep future anti-wraparound vacuums short; lower it (or 0) where rows are updated soon after insert and early freezing is wasted I/O and WAL.
How to change it
Any user can change it for their session with SET.
See it in context
VACUUM Free space map and visibility map XID wraparound and freezing
Related parameters
vacuum_freeze_min_age vacuum_freeze_table_age autovacuum_vacuum_insert_scale_factor