From e148443ddd95cd29edf4cc1de6188eb9cee029c5 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 17 Mar 2011 00:26:03 -0400
Subject: [PATCH] Document guc context values, and reference them from the
 config doc section.

Tom Lane
---
 doc/src/sgml/catalogs.sgml | 94 +++++++++++++++++++++++++++++++++++++-
 doc/src/sgml/config.sgml   | 10 ++--
 2 files changed, 99 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 64d1cda899..d0a8dc72cb 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -7628,7 +7628,7 @@
      <row>
       <entry><structfield>context</structfield></entry>
       <entry><type>text</type></entry>
-      <entry>Context required to set the parameter's value</entry>
+      <entry>Context required to set the parameter's value (see below)</entry>
      </row>
      <row>
       <entry><structfield>vartype</structfield></entry>
@@ -7692,6 +7692,98 @@
    </tgroup>
   </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
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 212f426b3c..7326771bcf 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -166,10 +166,12 @@ SET ENABLE_SEQSCAN TO OFF;
    </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
+    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.