explaining "context" column of pg_settings

Hi all,

The six different kinds of contexts in the pg_settings system view
aren't terribly well documented. The current doc page says only:
"Context required to set the parameter's value". A search through the
archives turned up only a brief explanation[1] of what "postmaster"
means for this setting. The recent book "PostgreSQL 9.0 High
Performance"[2] complains "The context field isn't documented very
well in the official manual."

I've put together a patch to help document these values based on the
comments in guc.h, the explanations in [2], and my own understanding.
My crude explanations could probably use some further wordsmithing and
check for accuracy :-)

I avoided just copy-pasting from guc.h, particulary because some of
the explanations struck me as confusing or incorrect. For instance:
* not all USERSET options may be set "any time", such as
transaction_isolation if you're already in the middle of a
transaction.
* I found the explanation for BACKEND confusing; it wasn't clear to
me from the comment that a pg_ctl reload would change such settings
for future backends.

I could attempt a patch for the comments in guc.h too, if there's interest.

Cheers
Josh

--
[1] http://archives.postgresql.org/pgsql-admin/2006-05/msg00067.php
[2] p. 126, section "Allowed change context"

Josh Kupershmidt <schmiddy(at)gmail(dot)com> writes:
> The six different kinds of contexts in the pg_settings system view
> aren't terribly well documented. The current doc page says only:
> "Context required to set the parameter's value". A search through the
> archives turned up only a brief explanation[1] of what "postmaster"
> means for this setting. The recent book "PostgreSQL 9.0 High
> Performance"[2] complains "The context field isn't documented very
> well in the official manual."

> I've put together a patch to help document these values based on the
> comments in guc.h, the explanations in [2], and my own understanding.
> My crude explanations could probably use some further wordsmithing and
> check for accuracy :-)

I did some work on this patch and attach an updated version. I'm not
however convinced that it's a good idea to bury this material in
catalogs.sgml --- I think few people ever read that chapter. Shouldn't
we put this into config.sgml instead, somewhere in section 18.1?

> I avoided just copy-pasting from guc.h, particulary because some of
> the explanations struck me as confusing or incorrect.

Well, your replacement explanations seemed even less correct ;-).
Also, I think what the text needs to emphasize is *how* to change
each setting type, so that prompted some of my editing.

regards, tom lane

Excerpts from Tom Lane's message of jue dic 16 21:11:49 -0300 2010:
> Josh Kupershmidt <schmiddy(at)gmail(dot)com> writes:
>
> > I've put together a patch to help document these values based on the
> > comments in guc.h, the explanations in [2], and my own understanding.
> > My crude explanations could probably use some further wordsmithing and
> > check for accuracy :-)
>
> I did some work on this patch and attach an updated version. I'm not
> however convinced that it's a good idea to bury this material in
> catalogs.sgml --- I think few people ever read that chapter. Shouldn't
> we put this into config.sgml instead, somewhere in section 18.1?

Perhaps we can replace the current "this setting requires a restart"
boilerplate with "this setting has context foo" in setting descriptions,
and have a pointer to wherever the description of each context is.

--
Álvaro Herrera <alvherre(at)commandprompt(dot)com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera <alvherre(at)commandprompt(dot)com> writes:
> Excerpts from Tom Lane's message of jue dic 16 21:11:49 -0300 2010:
>> I did some work on this patch and attach an updated version. I'm not
>> however convinced that it's a good idea to bury this material in
>> catalogs.sgml --- I think few people ever read that chapter. Shouldn't
>> we put this into config.sgml instead, somewhere in section 18.1?

> Perhaps we can replace the current "this setting requires a restart"
> boilerplate with "this setting has context foo" in setting descriptions,
> and have a pointer to wherever the description of each context is.

Hm, that's a thought. I've never been too happy with those boilerplate
sentences, mainly because they are of necessity brief and so don't
really convey all the implications. "This setting has context foo" is
brief too, but it could be a link to someplace that's more verbose.

If we were starting from scratch I'd want to try to think of some other
word than "context" to use here, but we're probably stuck with that one
because it's what's used in the pg_settings view.

regards, tom lane

Alvaro Herrera escreveu:
> Perhaps we can replace the current "this setting requires a restart"
> boilerplate with "this setting has context foo" in setting descriptions,
> and have a pointer to wherever the description of each context is.
>
.. or even foo_param (integer) (restart)

'restart' is a link describing the context. When I'm reading the manual
searching for a parameter description, sometimes it is not clear what is the
context; in this case, I need to query pg_settings to figure out what I have
to do to change that parameter. It would be fine if that information was
easily available.

--
Euler Taveira de Oliveira
http://www.timbira.com/

On Thu, Dec 16, 2010 at 7:11 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Josh Kupershmidt <schmiddy(at)gmail(dot)com> writes:
> I did some work on this patch and attach an updated version.

Thanks for taking a look at this. Your version is much more clear.

> I'm not
> however convinced that it's a good idea to bury this material in
> catalogs.sgml --- I think few people ever read that chapter.  Shouldn't
> we put this into config.sgml instead, somewhere in section 18.1?

Yeah, that seems like a better place for this text.

>> I avoided just copy-pasting from guc.h, particulary because some of
>> the explanations struck me as confusing or incorrect.
>
> Well, your replacement explanations seemed even less correct ;-).
> Also, I think what the text needs to emphasize is *how* to change
> each setting type, so that prompted some of my editing.

One piece in my patch which isn't in your version is this bit:

+ ... You may also
+ send a <systemitem>SIGHUP</systemitem> to an individual backend to cause
+ only that backend to reload <filename>postgresql.conf</filename>.

I was rather surprised when I learned this from the description in
guc.h of SIGHUP options. I tested by altering "full_page_writes" in
postgresql.conf and sending a SIGHUP to one backend, and sure enough
that backend picked up the change but new backends didn't. Unless this
feature is documented somewhere else, I think it would be helpful to
keep a snippet like this.

Josh

On Fri, Dec 17, 2010 at 10:00 PM, Josh Kupershmidt <schmiddy(at)gmail(dot)com> wrote:
> I was rather surprised when I learned this from the description in
> guc.h of SIGHUP options. I tested by altering "full_page_writes" in
> postgresql.conf and sending a SIGHUP to one backend, and sure enough
> that backend picked up the change but new backends didn't. Unless this
> feature is documented somewhere else, I think it would be helpful to
> keep a snippet like this.

I'm not sure we want people to rely on that behavior. Had we a way of
being sure that all backends would see an updated value at the same
time, we might be able to make some things that are PGC_POSTMASTER to
be PGC_SIGHUP instead.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Fri, Dec 17, 2010 at 1:08 PM, Euler Taveira de Oliveira
<euler(at)timbira(dot)com> wrote:
> Alvaro Herrera escreveu:
>> Perhaps we can replace the current "this setting requires a restart"
>> boilerplate with "this setting has context foo" in setting descriptions,
>> and have a pointer to wherever the description of each context is.
>>
> .. or even foo_param (integer) (restart)
>
> 'restart' is a link describing the context. When I'm reading the manual
> searching for a parameter description, sometimes it is not clear what is the
> context; in this case, I need to query pg_settings to figure out what I have
> to do to change that parameter. It would be fine if that information was
> easily available.

I definitely like the idea of explicitly stating the context of all
the GUCs in some concise yet clear way. I'm not totally sold on:

foo_param (integer) (restart)

since the (restart) is too similar to the (integer). I'm not sure I
have a better proposal offhand though. Maybe something like:

foo_param (integer) [postmaster context]

with "postmaster" a link to wherever we put the context descriptions.
I bet someone can find a prettier way, I'm still not happy with the
above..

Josh

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> On Fri, Dec 17, 2010 at 10:00 PM, Josh Kupershmidt <schmiddy(at)gmail(dot)com> wrote:
>> I was rather surprised when I learned this from the description in
>> guc.h of SIGHUP options. I tested by altering "full_page_writes" in
>> postgresql.conf and sending a SIGHUP to one backend, and sure enough
>> that backend picked up the change but new backends didn't. Unless this
>> feature is documented somewhere else, I think it would be helpful to
>> keep a snippet like this.

> I'm not sure we want people to rely on that behavior.

Yeah. It is documented somewhere in the SGML docs, IIRC, but I'm not
sure we want it up on the marquee.

regards, tom lane

What did we ever do with this idea?

---------------------------------------------------------------------------

Tom Lane wrote:
> Josh Kupershmidt <schmiddy(at)gmail(dot)com> writes:
> > The six different kinds of contexts in the pg_settings system view
> > aren't terribly well documented. The current doc page says only:
> > "Context required to set the parameter's value". A search through the
> > archives turned up only a brief explanation[1] of what "postmaster"
> > means for this setting. The recent book "PostgreSQL 9.0 High
> > Performance"[2] complains "The context field isn't documented very
> > well in the official manual."
>
> > I've put together a patch to help document these values based on the
> > comments in guc.h, the explanations in [2], and my own understanding.
> > My crude explanations could probably use some further wordsmithing and
> > check for accuracy :-)
>
> I did some work on this patch and attach an updated version. I'm not
> however convinced that it's a good idea to bury this material in
> catalogs.sgml --- I think few people ever read that chapter. Shouldn't
> we put this into config.sgml instead, somewhere in section 18.1?
>
> > I avoided just copy-pasting from guc.h, particulary because some of
> > the explanations struck me as confusing or incorrect.
>
> Well, your replacement explanations seemed even less correct ;-).
> Also, I think what the text needs to emphasize is *how* to change
> each setting type, so that prompted some of my editing.
>
> regards, tom lane
>

Content-Description: guc-context-docs-2.patch

>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Thu, Mar 10, 2011 at 10:09 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> What did we ever do with this idea?

Nobody felt like putting in the amount of work required to hammer out
the details, I think.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

I am unclear where to put this as well so I suggest we just put it in
catalogs.sgml and be done with it.

---------------------------------------------------------------------------

Tom Lane wrote:
> Josh Kupershmidt <schmiddy(at)gmail(dot)com> writes:
> > The six different kinds of contexts in the pg_settings system view
> > aren't terribly well documented. The current doc page says only:
> > "Context required to set the parameter's value". A search through the
> > archives turned up only a brief explanation[1] of what "postmaster"
> > means for this setting. The recent book "PostgreSQL 9.0 High
> > Performance"[2] complains "The context field isn't documented very
> > well in the official manual."
>
> > I've put together a patch to help document these values based on the
> > comments in guc.h, the explanations in [2], and my own understanding.
> > My crude explanations could probably use some further wordsmithing and
> > check for accuracy :-)
>
> I did some work on this patch and attach an updated version. I'm not
> however convinced that it's a good idea to bury this material in
> catalogs.sgml --- I think few people ever read that chapter. Shouldn't
> we put this into config.sgml instead, somewhere in section 18.1?
>
> > I avoided just copy-pasting from guc.h, particulary because some of
> > the explanations struck me as confusing or incorrect.
>
> Well, your replacement explanations seemed even less correct ;-).
> Also, I think what the text needs to emphasize is *how* to change
> each setting type, so that prompted some of my editing.
>
> regards, tom lane
>

Content-Description: guc-context-docs-2.patch

>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Fri, Mar 11, 2011 at 11:03 AM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>
> I am unclear where to put this as well so I suggest we just put it in
> catalogs.sgml and be done with it.
>

Please propose a specific patch so we can complain about it. :-)

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:
> On Fri, Mar 11, 2011 at 11:03 AM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> >
> > I am unclear where to put this as well so I suggest we just put it in
> > catalogs.sgml and be done with it.
> >
>
> Please propose a specific patch so we can complain about it. :-)

I am proposing Tom's:

http://archives.postgresql.org/pgsql-docs/2010-12/msg00003.php

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Robert Haas wrote:
>> Please propose a specific patch so we can complain about it. :-)

> I am proposing Tom's:
> http://archives.postgresql.org/pgsql-docs/2010-12/msg00003.php

It still seems like that material doesn't belong there. However, it's
largely a restatement of what's said in section 18.1 in a form that
matches up with the presentation used in the pg_settings view. Maybe
it's okay to apply it as-is and just check to make sure that 18.1 is not
missing any facts given here.

regards, tom lane

On Fri, Mar 11, 2011 at 12:37 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
>> Robert Haas wrote:
>>> Please propose a specific patch so we can complain about it.  :-)
>
>> I am proposing Tom's:
>>       http://archives.postgresql.org/pgsql-docs/2010-12/msg00003.php

That's actually a link to Josh's message, not the one from Tom; I
assume you mean the patch in Tom's reply.

> It still seems like that material doesn't belong there.  However, it's
> largely a restatement of what's said in section 18.1 in a form that
> matches up with the presentation used in the pg_settings view.  Maybe
> it's okay to apply it as-is and just check to make sure that 18.1 is not
> missing any facts given here.

AFAICS 18.1 doesn't really contain a clear enumeration of all the
different settings types. We ought to have that somewhere.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:
> On Fri, Mar 11, 2011 at 12:37 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Bruce Momjian <bruce(at)momjian(dot)us> writes:
> >> Robert Haas wrote:
> >>> Please propose a specific patch so we can complain about it. ?:-)
> >
> >> I am proposing Tom's:
> >> ? ? ? http://archives.postgresql.org/pgsql-docs/2010-12/msg00003.php
>
> That's actually a link to Josh's message, not the one from Tom; I
> assume you mean the patch in Tom's reply.
>
> > It still seems like that material doesn't belong there. ?However, it's
> > largely a restatement of what's said in section 18.1 in a form that
> > matches up with the presentation used in the pg_settings view. ?Maybe
> > it's okay to apply it as-is and just check to make sure that 18.1 is not
> > missing any facts given here.
>
> AFAICS 18.1 doesn't really contain a clear enumeration of all the
> different settings types. We ought to have that somewhere.

I took Tom's patch, applied it, and added appropriate text and links to
address the issues raised in this thread. Patch attached.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Applied.

---------------------------------------------------------------------------

Bruce Momjian wrote:
> Robert Haas wrote:
> > On Fri, Mar 11, 2011 at 12:37 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > > Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > >> Robert Haas wrote:
> > >>> Please propose a specific patch so we can complain about it. ?:-)
> > >
> > >> I am proposing Tom's:
> > >> ? ? ? http://archives.postgresql.org/pgsql-docs/2010-12/msg00003.php
> >
> > That's actually a link to Josh's message, not the one from Tom; I
> > assume you mean the patch in Tom's reply.
> >
> > > It still seems like that material doesn't belong there. ?However, it's
> > > largely a restatement of what's said in section 18.1 in a form that
> > > matches up with the presentation used in the pg_settings view. ?Maybe
> > > it's okay to apply it as-is and just check to make sure that 18.1 is not
> > > missing any facts given here.
> >
> > AFAICS 18.1 doesn't really contain a clear enumeration of all the
> > different settings types. We ought to have that somewhere.
>
> I took Tom's patch, applied it, and added appropriate text and links to
> address the issues raised in this thread. Patch attached.
>
> --
> Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
> EnterpriseDB http://enterprisedb.com
>
> + It's impossible for everything to be true. +

[ text/x-diff is unsupported, treating like TEXT/PLAIN ]

> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
> new file mode 100644
> index 64d1cda..d0a8dc7
> *** a/doc/src/sgml/catalogs.sgml
> --- b/doc/src/sgml/catalogs.sgml
> ***************
> *** 7628,7634 ****
> <row>
> <entry><structfield>context</structfield></entry>
> <entry><type>text</type></entry>
> ! <entry>Context required to set the parameter's value</entry>
> </row>
> <row>
> <entry><structfield>vartype</structfield></entry>
> --- 7628,7634 ----
> <row>
> <entry><structfield>context</structfield></entry>
> <entry><type>text</type></entry>
> ! <entry>Context required to set the parameter's value (see below)</entry>
> </row>
> <row>
> <entry><structfield>vartype</structfield></entry>
> ***************
> *** 7693,7698 ****
> --- 7693,7790 ----
> </table>
>
> <para>
> + There are several possible values of <structfield>context</structfield>.
> + In order of decreasing difficulty of changing the setting, they are:
> + </para>
> +
> + <variablelist>
> + <varlistentry>
> + <term><literal>internal</literal></term>
> + <listitem>
> + <para>
> + These settings cannot be changed directly; they reflect internally
> + determined values. Some of them may be adjustable by rebuilding the
> + server with different configuration options, or by changing options
> + supplied to <command>initdb</command>.
> + </para>
> + </listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal>postmaster</literal></term>
> + <listitem>
> + <para>
> + These settings can only be applied when the server starts, so any change
> + requires restarting the server. Values for these settings are typically
> + stored in the <filename>postgresql.conf</filename> file, or passed on
> + the command line when starting the server. Of course, settings with any
> + of the lower <structfield>context</structfield> types can also be
> + set at server start time.
> + </para>
> + </listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal>sighup</literal></term>
> + <listitem>
> + <para>
> + Changes to these settings can be made in
> + <filename>postgresql.conf</filename> without restarting the server.
> + Send a <systemitem>SIGHUP</systemitem> signal to the postmaster to
> + cause it to re-read <filename>postgresql.conf</filename> and apply
> + the changes. The postmaster will also forward the
> + <systemitem>SIGHUP</systemitem> signal to its child processes so that
> + they all pick up the new value.
> + </para>
> + </listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal>backend</literal></term>
> + <listitem>
> + <para>
> + Changes to these settings can be made in
> + <filename>postgresql.conf</filename> without restarting the server;
> + they can also be set for a particular session in the connection request
> + packet (for example, via <application>libpq</>'s <literal>PGOPTIONS</>
> + environment variable). However, these settings never change in a
> + session after it is started. If you change them in
> + <filename>postgresql.conf</filename>, send a
> + <systemitem>SIGHUP</systemitem> signal to the postmaster to cause it to
> + re-read <filename>postgresql.conf</filename>. The new values will only
> + affect subsequently-launched sessions.
> + </para>
> + </listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal>superuser</literal></term>
> + <listitem>
> + <para>
> + These settings can be set from <filename>postgresql.conf</filename>,
> + or within a session via the <command>SET</> command; but only superusers
> + can change them via <command>SET</>. Changes in
> + <filename>postgresql.conf</filename> will affect existing sessions
> + only if no session-local value has been established with <command>SET</>.
> + </para>
> + </listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal>user</literal></term>
> + <listitem>
> + <para>
> + These settings can be set from <filename>postgresql.conf</filename>,
> + or within a session via the <command>SET</> command. Any user is
> + allowed to change his session-local value. Changes in
> + <filename>postgresql.conf</filename> will affect existing sessions
> + only if no session-local value has been established with <command>SET</>.
> + </para>
> + </listitem>
> + </varlistentry>
> + </variablelist>
> +
> + <para>
> + See <xref linkend="config-setting"> for more information about the various
> + ways to change these parameters.
> + </para>
> +
> + <para>
> The <structname>pg_settings</structname> view cannot be inserted into or
> deleted from, but it can be updated. An <command>UPDATE</command> applied
> to a row of <structname>pg_settings</structname> is equivalent to executing
> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
> new file mode 100644
> index a4c1e84..a55a800
> *** a/doc/src/sgml/config.sgml
> --- b/doc/src/sgml/config.sgml
> *************** SET ENABLE_SEQSCAN TO OFF;
> *** 166,175 ****
> </para>
>
> <para>
> ! The virtual table <structname>pg_settings</structname>
> ! (described in <xref linkend="view-pg-settings">) also allows
> ! displaying and updating session run-time parameters. It is equivalent
> ! to <command>SHOW</> and <command>SET</>, but can be more convenient
> to use because it can be joined with other tables, or selected from using
> any desired selection condition. It also contains more information about
> what values are allowed for the parameters.
> --- 166,177 ----
> </para>
>
> <para>
> ! The virtual table <structname>pg_settings</structname> also allows
> ! displaying and updating session run-time parameters; see <xref
> ! linkend="view-pg-settings"> for details and a description of the
> ! different variable types and when they can be changed.
> ! <structname>pg_settings</structname> is equivalent to <command>SHOW</>
> ! and <command>SET</>, but can be more convenient
> to use because it can be joined with other tables, or selected from using
> any desired selection condition. It also contains more information about
> what values are allowed for the parameters.

>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +