Docs: Clarify that SIGHUP/reload does not update all GUCs for existing sessions
Hello,
While reading the *“Server Configuration”* documentation, I noticed a
potentially misleading statement in:
https://www.postgresql.org/docs/current/runtime-config.html
(Chapter 19 → 19.1.2 “Parameter Interaction via the Configuration File”)
The text says that when the postmaster receives SIGHUP/reload, it
propagates the signal to all server processes “so that existing sessions
also adopt the new values”.
As written, this can be interpreted to mean that any changed parameter in
postgresql.conf will be adopted by already-connected sessions after a
reload. However, many GUCs have context “backend” or “superuser-backend”
and do not change within an already-started session; those changes only
affect subsequently-launched sessions.
*Suggestion*: qualify the sentence to indicate that existing sessions will
pick up changes only for parameters whose context allows it (e.g.,
“sighup”), and that “backend” / “superuser-backend” settings won’t change
for existing sessions.
*Proposed wording (illustrative diff):*
*"*
*- The main server process also propagates this signal to all currently
running server processes,*
*- so that existing sessions also adopt the new values (this will happen
after they complete any- currently-executing client command).*
*+ The main server process also propagates this signal to all currently
running server processes.+ Existing sessions will adopt new values for
parameters whose context allows changes at reload+ time (for example,
sighup). Parameters whose context is backend or superuser-backend do not+
change within an already-started session; changes to those only affect
subsequently-launched+ sessions.*
"
Happy to send a formal patch if you would like.
Thanks,
Balkrishna
Balkrishna Pandey <balkrishna.pandey@gmail.com> writes:
*Proposed wording (illustrative diff):*
*+ The main server process also propagates this signal to all currently
running server processes.+ Existing sessions will adopt new values for
parameters whose context allows changes at reload+ time (for example,
sighup). Parameters whose context is backend or superuser-backend do not+
change within an already-started session; changes to those only affect
subsequently-launched+ sessions.*
This seems to me to be getting way too far into the implementation weeds,
while still failing to cover everything. For example, it's also true
that a SET within the session will override postgresql.conf.
The main intent of the code is that SIGHUP will propagate a
postgresql.conf change into an existing session if that session
had been using the previous value from postgresql.conf. If its
source for the active value was something else, nothing changes.
You can argue about whether "backend"-context GUCs are an exception
to that rule, but I think our statement in the docs should be
about at that level of complexity.
regards, tom lane
Hi Tom,
Thanks , that is a helpful framing, and I agree my first suggestion went
too deep into GUC “context” details and still didn’t capture the full rule
(e.g., session-level SET overriding postgresql.conf).
What I was trying to address is the impression a reader may get from “so
that existing sessions also adopt the new values,” namely that *all*
changed settings automatically take effect everywhere.
Based on your explanation, I think the doc should state the behavior at the
“source of active value” level:
-
On SIGHUP, backends re-read postgresql.conf
-
A backend will only see a changed value take effect if it was previously
using the value from postgresql.conf
-
If the active value came from elsewhere (e.g., a SET in the session,
ALTER ROLE/DATABASE, etc.), then nothing changes in that session
Would something like the following be closer to the right level of
complexity?
-
The main server process also propagates this signal to all currently
running server processes, so that existing sessions also adopt the new
values (this will happen after they complete any currently-executing client
command).
-
The main server process also propagates this signal to all currently
running server processes. After completing any currently-executing command,
existing sessions re-read postgresql.conf and will adopt changed values for
parameters where their active setting was coming from postgresql.conf. If a
session’s active value was set from another source (for example, a SET
command or role/database settings), the session’s behavior will not change.
Does this phrasing align with what you had in mind? I appreciate your
feedback
Thanks in advance!
Regards,
Balkrishna
On Wed, Jan 14, 2026 at 12:17 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Show quoted text
Balkrishna Pandey <balkrishna.pandey@gmail.com> writes:
*Proposed wording (illustrative diff):*
*+ The main server process also propagates this signal to all currently
running server processes.+ Existing sessions will adopt new values for
parameters whose context allows changes at reload+ time (for example,
sighup). Parameters whose context is backend or superuser-backend do not+
change within an already-started session; changes to those only affect
subsequently-launched+ sessions.*This seems to me to be getting way too far into the implementation weeds,
while still failing to cover everything. For example, it's also true
that a SET within the session will override postgresql.conf.The main intent of the code is that SIGHUP will propagate a
postgresql.conf change into an existing session if that session
had been using the previous value from postgresql.conf. If its
source for the active value was something else, nothing changes.
You can argue about whether "backend"-context GUCs are an exception
to that rule, but I think our statement in the docs should be
about at that level of complexity.regards, tom lane
Please follow our example and avoid top-posting.
On Tuesday, January 13, 2026, Balkrishna Pandey <balkrishna.pandey@gmail.com>
wrote:
What I was trying to address is the impression a reader may get from “so
that existing sessions also adopt the new values,” namely that *all*
changed settings automatically take effect everywhere.
Yeah, getting rid of the somewhat unclear word “adopt” might be good.
Maybe say: “update their internal setting value hierarchy”.
David J.