Re: explaining "context" column of pg_settings

Robert Haas wrote:
> On Fri, Mar 11, 2011 at 12:37 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Bruce Momjian <bruce@momjian.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@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
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.