[PATCH] doc: Fix autovacuum_max_workers and autovacuum_worker_slots descriptions

From: Joao Rito <joaovictor(dot)rito(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: [PATCH] doc: Fix autovacuum_max_workers and autovacuum_worker_slots descriptions
Date: 2026-11-19 00:45:20
Message-ID: 20261119004520.10067-1-joaovictor.rito@gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

The documentation for autovacuum_max_workers says that a value higher than
autovacuum_worker_slots has no effect. In fact, check_av_worker_gucs()
reports a WARNING in that case, and the server starts at most
autovacuum_worker_slots workers.

Also document that slots beyond autovacuum_max_workers are kept in
reserve (see av_worker_available()), so autovacuum_max_workers can be
raised with a configuration reload, up to autovacuum_worker_slots.
This is the purpose of autovacuum_worker_slots, as described in the
message of commit c758119e5.
---
Hi,

The docs for autovacuum_max_workers say that a value higher than autovacuum_worker_slots "will have no effect". On current master the server logs a WARNING instead, and starts at most autovacuum_worker_slots workers. I saw this with slots=16 and max_workers=20, after changing max_workers and reloading:

WARNING: "autovacuum_max_workers" (20) should be less than or equal to "autovacuum_worker_slots" (16)
DETAIL: The server will only start up to "autovacuum_worker_slots" (16) autovacuum workers at a given time.

As I read autovacuum.c, this WARNING is logged at startup, and on reload only when autovacuum_max_workers changed.

The attached patch changes that sentence. It also adds a short paragraph to autovacuum_worker_slots. It says that slots above autovacuum_max_workers are kept in reserve, so max_workers can be raised by a reload, up to slots. I based this on the message of commit c758119e5 and on av_worker_available().

Does this direction make sense? I am happy to shorten or reword it.

What I did not test:
- Only one platform (Debian 12, x86_64, in a container), non-assert build.
- I checked the behavior with one reload (16 slots, 20 workers). I did not run autovacuum under load to confirm the reserve.
- I did not check the mailing list archives for earlier discussion.
- I did not read the rendered HTML; only xmllint validation and the HTML build passed.

Thanks for your time.
Joao Rito

doc/src/sgml/config.sgml | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 886e8c4..88fe68d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9508,6 +9508,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
When changing this value, consider also adjusting
<xref linkend="guc-autovacuum-max-workers"/>.
</para>
+ <para>
+ If this value is higher than
+ <xref linkend="guc-autovacuum-max-workers"/>, the extra slots are kept
+ in reserve. They allow <varname>autovacuum_max_workers</varname> to be
+ increased, up to the value of this parameter, by reloading the
+ configuration without a restart.
+ </para>
</listitem>
</varlistentry>

@@ -9526,8 +9533,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</para>
<para>
Note that a setting for this value which is higher than
- <xref linkend="guc-autovacuum-worker-slots"/> will have no effect,
- since autovacuum workers are taken from the pool of slots established
+ <xref linkend="guc-autovacuum-worker-slots"/> causes a
+ <literal>WARNING</literal> to be logged at server start and whenever
+ <varname>autovacuum_max_workers</varname> is changed, and the server will start at most
+ <varname>autovacuum_worker_slots</varname> autovacuum workers, since
+ autovacuum workers are taken from the pool of slots established
by that setting.
</para>
</listitem>
--
2.39.5

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Ajin Cherian 2026-11-19 00:47:53 Re: Add a hook for handling logical decoding messages on subscribers.
Previous Message Masahiko Sawada 2026-11-19 00:33:12 Re: Injection point: fix race condition between attach and cleanup