[PATCH] doc: Fix autovacuum_max_workers and autovacuum_worker_slots descriptions
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
Hi,
At Wed, 18 Nov 2026 21:45:20 -0300, Joao Rito <joaovictor.rito@gmail.com> wrote in
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.
I agree with the general direction of the proposal. However, I don't
think it's necessary to document when the WARNING is issued, since the
existing documentation already explains that values exceeding the
limit have no effect.
I think revising the existing text, rather than simply adding new
text, would make the proposed changes more concise and easier to
understand.
Also, the current term "backend slots" might give the misleading
impression that these slots are included in max_connections, so I
think it would be better to change "backend slots to reserve for" to
"slots to allocate for" in the description of autovacuum_worker_slots.
For the same reason, I think "backend slots" should also be changed to
"slots" in the short_desc entry in guc_parameters.dat.
The changes would look something like this:
====
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 886e8c44847..726d52afa31 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9499,14 +9499,16 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</term>
<listitem>
<para>
- Specifies the number of backend slots to reserve for autovacuum worker
+ Specifies the number of slots to allocate for autovacuum worker
processes. The default is typically 16 slots, but might be less if
your kernel settings will not support it (as determined during initdb).
This parameter can only be set at server start.
</para>
<para>
- When changing this value, consider also adjusting
- <xref linkend="guc-autovacuum-max-workers"/>.
+ Setting this parameter higher than
+ <xref linkend="guc-autovacuum-max-workers"/> allows it to be
+ increased up to this value by reloading the configuration without
+ restarting the server.
</para>
</listitem>
</varlistentry>
diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index 184fcf49080..3c2b7c32198 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -294,7 +294,7 @@
# see max_connections
{ name => 'autovacuum_worker_slots', type => 'int', context => 'PGC_POSTMASTER', group => 'VACUUM_AUTOVACUUM',
- short_desc => 'Sets the number of backend slots to allocate for autovacuum workers.',
+ short_desc => 'Sets the number of slots to allocate for autovacuum workers.',
variable => 'autovacuum_worker_slots',
boot_val => '16',
min => '1',
====
Regards,
--
Kyotaro Horiguchi
NTT Open Source Software Center
Reword the autovacuum_worker_slots description to say that it sets the
number of slots to allocate, and explain that autovacuum_max_workers can
be raised up to this value by reloading the configuration. Update the
GUC short description to match.
---
Hi Horiguchi-san,
Thank you very much for the review and for the diff. I rewrote the patch from it.
Changes in v2:
- Reword the existing text of autovacuum_worker_slots instead of adding a new paragraph. I used your wording: "slots to allocate for autovacuum worker processes", and "Setting this parameter higher than autovacuum_max_workers allows it to be increased up to this value by reloading the configuration without restarting the server".
- Drop the sentences about when the WARNING is logged, and leave the autovacuum_max_workers text as it was.
- Change the short_desc in guc_parameters.dat to "Sets the number of slots to allocate for autovacuum workers."
I tested on master (ba11c48) with --enable-cassert. The patch also applies cleanly with "git am" on a newer master (1191073). The documentation passes "make -C doc/src/sgml check" and the HTML build. "SELECT short_desc FROM pg_settings WHERE name = 'autovacuum_worker_slots'" returns the new text. "make check" passed (243 tests), and so did src/test/modules/test_misc (169 tests; 5 of 16 test files were skipped because the build has no injection points).
What I did not test: I did not read the rendered HTML. I tested only one platform. I did not check whether translations (.po files) need a change for the short_desc.
Thank you again,
Joao Rito
doc/src/sgml/config.sgml | 7 ++++---
src/backend/utils/misc/guc_parameters.dat | 2 +-
2 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 886e8c4..cf95130 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9499,14 +9499,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</term>
<listitem>
<para>
- Specifies the number of backend slots to reserve for autovacuum worker
+ Specifies the number of slots to allocate for autovacuum worker
processes. The default is typically 16 slots, but might be less if
your kernel settings will not support it (as determined during initdb).
This parameter can only be set at server start.
</para>
<para>
- When changing this value, consider also adjusting
- <xref linkend="guc-autovacuum-max-workers"/>.
+ Setting this parameter higher than <xref linkend="guc-autovacuum-max-workers"/>
+ allows it to be increased up to this value by reloading the configuration
+ without restarting the server.
</para>
</listitem>
</varlistentry>
diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index 184fcf4..3c2b7c3 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -294,7 +294,7 @@
# see max_connections
{ name => 'autovacuum_worker_slots', type => 'int', context => 'PGC_POSTMASTER', group => 'VACUUM_AUTOVACUUM',
- short_desc => 'Sets the number of backend slots to allocate for autovacuum workers.',
+ short_desc => 'Sets the number of slots to allocate for autovacuum workers.',
variable => 'autovacuum_worker_slots',
boot_val => '16',
min => '1',
--
2.39.5