Received: from maia.hub.org (maia-3.hub.org [200.46.204.243])
	by mail.postgresql.org (Postfix) with ESMTP id 435D41337B6E
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Thu, 16 Dec 2010 20:11:58 -0400 (AST)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.243]) (amavisd-maia,
	port 10024) with ESMTP id 42988-05 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Fri, 17 Dec 2010 00:11:50 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from sss.pgh.pa.us (sss.pgh.pa.us [66.207.139.130])
	by mail.postgresql.org (Postfix) with ESMTP id 62EC31337B61
	for <pgsql-docs@postgresql.org>; Thu, 16 Dec 2010 20:11:50 -0400 (AST)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.2/8.14.2) with ESMTP id oBH0BnB8017755;
	Thu, 16 Dec 2010 19:11:49 -0500 (EST)
To: Josh Kupershmidt <schmiddy@gmail.com>
cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: explaining "context" column of pg_settings 
In-reply-to: <AANLkTi=rY=Ffo3JkU1eKROG0cDnr0PKaejrEbTSjffnu@mail.gmail.com> 
References: <AANLkTi=rY=Ffo3JkU1eKROG0cDnr0PKaejrEbTSjffnu@mail.gmail.com>
Comments: In-reply-to Josh Kupershmidt <schmiddy@gmail.com>
	message dated "Sat, 04 Dec 2010 19:16:49 -0500"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <17741.1292544660.0@sss.pgh.pa.us>
Date: Thu, 16 Dec 2010 19:11:49 -0500
Message-ID: <17754.1292544709@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.91 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	T_RP_MATCHES_RCVD=-0.01
X-Spam-Level: 
X-Archive-Number: 201012/17
X-Sequence-Number: 6253

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <17741.1292544660.1@sss.pgh.pa.us>

Josh Kupershmidt <schmiddy@gmail.com> 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


------- =_aaaaaaaaaa0
Content-Type: text/x-patch; charset="us-ascii"
Content-ID: <17741.1292544660.2@sss.pgh.pa.us>
Content-Description: guc-context-docs-2.patch
Content-Transfer-Encoding: quoted-printable

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</structfiel=
d>.
+    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 t=
he
+       server with different configuration options, or by changing option=
s
+       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 typ=
ically
+       stored in the <filename>postgresql.conf</filename> file, or passed=
 on
+       the command line when starting the server.  Of course, settings wi=
th 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 t=
hat
+       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 re=
quest
+       packet (for example, via <application>libpq</>'s <literal>PGOPTION=
S</>
+       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 supe=
rusers
+       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=3D"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> ap=
plied
     to a row of <structname>pg_settings</structname> is equivalent to exe=
cuting

------- =_aaaaaaaaaa0--