Re: Eagerly scan all-visible pages to amortize aggressive vacuum

On Thu, Jul 31, 2025 at 7:05 AM Pavel Luzanov <p(dot)luzanov(at)postgrespro(dot)ru> wrote:
>
> I have a question about the documentation.
>
> From description of the vacuum_max_eager_freeze_failure_rate [1]
>
> "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."
>
> It seems that after reaching the vacuum_max_eager_freeze_failure_rate,
> the eager scanning of this table will be stopped. But in the source code
> [2]:
>
> * cap. The failure count is reset for each region of the table --
> comprised
> * of EAGER_SCAN_REGION_SIZE blocks. In each region, we tolerate
> * vacuum_max_eager_freeze_failure_rate of EAGER_SCAN_REGION_SIZE failures
> * before suspending eager scanning until the end of the region.
>
> From this description, vacuum_max_eager_freeze_failure_rate limit
> applies to a region of EAGER_SCAN_REGION_SIZE pages, but not to the
> whole table.

Right, I looked at the fact that it is temporarily disabled per region
and then re-enabled as an implementation detail that would be more
confusing to document. If you eager scan and fail to freeze 3% of each
region, you'll have eager scanned and failed to freeze 3% of the
blocks in the table -- so the total cap is the same. You don't see the
eager scan counts until the end of vacuuming, so from the user's
perspective it's the same.

Documenting it means exposing more about the algorithm than seems
useful or actionable to the user.

Is there something you would do differently from a user perspective if
you knew that it was being temporarily disabled and reenabled for
specific regions of the table?

- Melanie