Re: explaining "context" column of pg_settings

Applied.

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

Bruce Momjian wrote:
> 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. +

[ 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@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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