Docs: Clarify that SIGHUP/reload does not update all GUCs for existing sessions

From: Balkrishna Pandey <balkrishna(dot)pandey(at)gmail(dot)com>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Subject: Docs: Clarify that SIGHUP/reload does not update all GUCs for existing sessions
Date: 2026-01-14 03:20:31
Message-ID: CAEdRop3fo784VmdeEWc3HXn-_x-tTx6AFXgNh78WGrhKkqvgtw@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

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

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Andreas Karlsson 2026-01-14 06:43:35 Re: Parallelizing startup with many databases
Previous Message Fujii Masao 2026-01-13 13:57:54 Re: file_fdw: Add missing docs for the DEFAULT option