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(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. +