Josh Kupershmidt <[email protected]> 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
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index ef35fd9..531c979 100644
*** a/doc/src/sgml/catalogs.sgml
--- b/doc/src/sgml/catalogs.sgml
***************
*** 7116,7122 ****
<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>
--- 7116,7122 ----
<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>
***************
*** 7181,7186 ****
--- 7181,7278 ----
</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
--
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
