Received: from malur.postgresql.org ([217.196.149.56])
 by arkaria.postgresql.org with esmtp (Exim 4.80) (envelope-from
 <pgsql-docs-owner+M8093=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
 id 1XRQr4-0006FH-9d
 for pgsql-docs@arkaria.postgresql.org; Tue, 09 Sep 2014 19:13:30 +0000
Received: from localhost ([127.0.0.1] helo=postgresql.org)
 by malur.postgresql.org with smtp (Exim 4.80) (envelope-from
 <pgsql-docs-owner+M8093=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
 id 1XRQr3-0002xp-2q
 for pgsql-docs@arkaria.postgresql.org; Tue, 09 Sep 2014 19:13:29 +0000
Received: from makus.postgresql.org ([2001:4800:1501:1::229])
 by malur.postgresql.org with esmtps (TLS1.2:DHE_RSA_AES_256_CBC_SHA256:256)
 (Exim 4.80) (envelope-from <bruce@momjian.us>) id 1XRQr1-0002xg-O4
 for pgsql-docs@postgresql.org; Tue, 09 Sep 2014 19:13:28 +0000
Received: from momjian.us ([72.94.173.45])
 by makus.postgresql.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256)
 (Exim 4.80) (envelope-from <bruce@momjian.us>) id 1XRQqt-0008E5-LD
 for pgsql-docs@postgresql.org; Tue, 09 Sep 2014 19:13:25 +0000
Received: from bruce by momjian.us with local (Exim 4.72)
 (envelope-from <bruce@momjian.us>)
 id 1XRQqr-0003u1-Te; Tue, 09 Sep 2014 15:13:17 -0400
Date: Tue, 9 Sep 2014 15:13:17 -0400
From: Bruce Momjian <bruce@momjian.us>
To: David Johnston <david.g.johnston@gmail.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: [9.3] Should we mention "set_config(...)" in 18.1.3 in
 Server Configuration?
Message-ID: <20140909191317.GF16663@momjian.us>
References: <1400698826956-5804655.post@n5.nabble.com>
 <2916.1400704666@sss.pgh.pa.us>
 <CAKFQuwbjqT7jHAULPM0YB7x=+qpddH5bYnGmwZ+yVhNBb6SVnQ@mail.gmail.com>
 <CAKFQuwa5d3EUBGwYN1mA6FKO1K7kO+Wci8yM57QNHdEGQ9TJ9g@mail.gmail.com>
 <CAKFQuwbbOZRqmnx-XRyd+viT+MCAH6TVc0yn1aJtG5MdSNAWpA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="GvXjxJ+pjyke8COw"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKFQuwbbOZRqmnx-XRyd+viT+MCAH6TVc0yn1aJtG5MdSNAWpA@mail.gmail.com>
User-Agent: Mutt/1.5.20 (2009-06-14)
X-Pg-Spam-Score: -4.4 (----)
List-Archive: <http://archives.postgresql.org/pgsql-docs>
List-Help: <mailto:majordomo@postgresql.org?body=help>
List-ID: <pgsql-docs.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@postgresql.org>
List-Post: <mailto:pgsql-docs@postgresql.org>
List-Subscribe: <mailto:majordomo@postgresql.org?body=sub%20pgsql-docs>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
X-Mailing-List: pgsql-docs
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org


--GvXjxJ+pjyke8COw
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On Thu, Jun 12, 2014 at 11:32:49AM -0400, David Johnston wrote:
> This addition still needs some work as well as the patch as a whole (see my
> comments above).  The attached PDF is the page that results from "make html";
> the original patch has been re-attached as well and -hackers copied given the
> lack of response on -doc.
> 
> I am hoping this change would be something that could be included in 9.4; I
> believe the enhancements would be most beneficial to newcomers who are just
> getting started with PostgreSQL and would be using 9.4 as their starting point.

[hackers CC removed]

I have reviewed and updated this reworking of our configuration settings
documentation and feel it is ready for application to head and 9.4; 
attached.

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

  + Everyone has their own god. +

--GvXjxJ+pjyke8COw
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="config.diff"

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index 49547ee..156c264
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
***************
*** 11,17 ****
    <para>
     There are many configuration parameters that affect the behavior of
     the database system. In the first section of this chapter, we
!    describe how to set configuration parameters. The subsequent sections
     discuss each parameter in detail.
    </para>
  
--- 11,17 ----
    <para>
     There are many configuration parameters that affect the behavior of
     the database system. In the first section of this chapter, we
!    describe how to interact with configuration parameters. The subsequent sections
     discuss each parameter in detail.
    </para>
  
***************
*** 23,69 ****
  
      <para>
       All parameter names are case-insensitive. Every parameter takes a
!      value of one of five types: Boolean, integer, floating point,
!      string or enum. Boolean values can be written as <literal>on</literal>,
!      <literal>off</literal>, <literal>true</literal>,
!      <literal>false</literal>, <literal>yes</literal>,
!      <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
!      (all case-insensitive) or any unambiguous prefix of these.
      </para>
  
!     <para>
!      Some settings specify a memory or time value.  Each of these has an
!      implicit unit, which is either kilobytes, blocks (typically eight
!      kilobytes), milliseconds, seconds, or minutes.  Default units can be
!      found by referencing <structname>pg_settings</>.<structfield>unit</>.
!      For convenience,
!      a different unit can also be specified explicitly.  Valid memory units
!      are <literal>kB</literal> (kilobytes), <literal>MB</literal>
!      (megabytes), <literal>GB</literal> (gigabytes), and <literal>TB</literal> (terabytes); valid time units
!      are <literal>ms</literal> (milliseconds), <literal>s</literal>
!      (seconds), <literal>min</literal> (minutes), <literal>h</literal>
!      (hours), and <literal>d</literal> (days).  Note that the multiplier
!      for memory units is 1024, not 1000.
!     </para>
  
!     <para>
!      Parameters of type <quote>enum</> are specified in the same way as string
!      parameters, but are restricted to a limited set of values.  The allowed
!      values can be found
!      from <structname>pg_settings</>.<structfield>enumvals</>.
!      Enum parameter values are case-insensitive.
!     </para>
     </sect2>
  
     <sect2 id="config-setting-configuration-file">
!     <title>Setting Parameters via the Configuration File</title>
  
      <para>
!      One way to set these parameters is to edit the file
       <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
       which is normally kept in the data directory.  (A default copy is
!      installed there when the database cluster directory is
!      initialized.)  An example of what this file might look like is:
  <programlisting>
  # This is a comment
  log_connections = yes
--- 23,121 ----
  
      <para>
       All parameter names are case-insensitive. Every parameter takes a
!      value of one of five types: boolean, integer, floating point,
!      string, or enum.
      </para>
  
!     <itemizedlist>
  
!      <listitem>
!       <para>
!        <emphasis>Boolean</emphasis>: Values can be written as
!        <literal>on</literal>,
!        <literal>off</literal>,
!        <literal>true</literal>,
!        <literal>false</literal>,
!        <literal>yes</literal>,
!        <literal>no</literal>,
!        <literal>1</literal>,
!        <literal>0</literal>
!        (all case-insensitive) or any unambiguous prefix of these.
!       </para>
!      </listitem>
! 
!      <listitem>
!       <para>
!        <emphasis>String:</emphasis> Enclose the value in
!        single-quotes. Values are case-insensitive.  If multiple values
!        are allowed, separate them with commas.
!       </para>
!      </listitem>
! 
!      <listitem>
!       <para>
!        <emphasis>Numeric</emphasis> (integer and floating point): Do not use
!        single-quotes (unless otherwise required) or thousand separators.
!       </para>
!      </listitem>
! 
!      <listitem>
!       <para>
!        <emphasis>Numeric or String with Unit (Memory &amp;
!        Time):</emphasis> These have an implicit unit, which is
!        either kilobytes, blocks (typically eight kilobytes),
!        milliseconds, seconds, or minutes.  An numeric value
!        will use the default, which can be found by referencing
!        <structname>pg_settings</>.<structfield>unit</>.  For convenience,
!        a different unit can also be specified explicitly via a string
!        value. It is case-sensitive and may include whitespace between
!        the value and the unit.
! 
!        <itemizedlist>
!         <listitem>
!          <para>
!           Valid memory units are <literal>kB</literal> (kilobytes),
!           <literal>MB</literal> (megabytes), <literal>GB</literal>
!           (gigabytes), and <literal>TB</literal> (terabytes).
!           The multiplier for memory units is 1024, not 1000.
!          </para>
!         </listitem>
!  
!         <listitem>
!          <para>
!           Valid time units are <literal>ms</literal> (milliseconds),
!           <literal>s</literal> (seconds), <literal>min</literal> (minutes),
!           <literal>h</literal> (hours), and <literal>d</literal> (days).
!          </para>
!         </listitem>
!        </itemizedlist>
!       </para>
!      </listitem>
! 
!      <listitem>
!       <para>
!        <emphasis><quote>enum</>:</emphasis> These are specified
!        in the same way as string parameters, but are restricted
!        to a limited set of values that can be queried from
!        <structname>pg_settings</>.<structfield>enumvals</>:
! <programlisting>
! SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
! </programlisting>
!        Enum parameter values are case-insensitive.
!       </para>
!      </listitem>
!     </itemizedlist>
     </sect2>
  
     <sect2 id="config-setting-configuration-file">
!     <title>Parameter Interaction via Configuration File</title>
  
      <para>
!      The primary way to set these parameters is to edit the file
       <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
       which is normally kept in the data directory.  (A default copy is
!      installed when the database cluster directory is initialized.)
!      An example of what this file might look like is:
  <programlisting>
  # This is a comment
  log_connections = yes
*************** log_destination = 'syslog'
*** 71,197 ****
  search_path = '"$user", public'
  shared_buffers = 128MB
  </programlisting>
!      One parameter is specified per line. The equal sign between name and
!      value is optional. Whitespace is insignificant and blank lines are
!      ignored. Hash marks (<literal>#</literal>) designate the remainder of the
!      line as a comment.  Parameter values that are not simple identifiers or
!      numbers must be single-quoted.  To embed a single quote in a parameter
!      value, write either two quotes (preferred) or backslash-quote.
      </para>
  
      <para>
       <indexterm>
!       <primary>SIGHUP</primary>
       </indexterm>
       The configuration file is reread whenever the main server process
       receives a <systemitem>SIGHUP</> signal;  this is most easily done by
       running <literal>pg_ctl reload</> from the command-line or by calling
       the SQL function <function>pg_reload_conf()</function>. The main
!      server process
!      also propagates this signal to all currently running server
!      processes so that existing sessions also get the new
!      value. Alternatively, you can send the signal to a single server
!      process directly.  Some parameters can only be set at server start;
!      any changes to their entries in the configuration file will be ignored
!      until the server is restarted.  Invalid parameter settings in the
!      configuration file are likewise ignored (but logged) during
!      <systemitem>SIGHUP</> processing.
      </para>
     </sect2>
  
!    <sect2 id="config-setting-other-methods">
!     <title>Other Ways to Set Parameters</title>
  
!     <para>
!      A second way to set these configuration parameters is to give them
!      as a command-line option to the <command>postgres</command> command,
!      such as:
! <programlisting>
! postgres -c log_connections=yes -c log_destination='syslog'
! </programlisting>
!      Command-line options override any conflicting settings in
!      <filename>postgresql.conf</filename>.  Note that this means you won't
!      be able to change the value on-the-fly by editing
!      <filename>postgresql.conf</filename>, so while the command-line
!      method might be convenient, it can cost you flexibility later.
!     </para>
  
!     <para>
!      Occasionally it is useful to give a command line option to
!      one particular session only. The environment variable
!      <envar>PGOPTIONS</envar> can be used for this purpose on the
!      client side:
! <programlisting>
! env PGOPTIONS='-c geqo=off' psql
! </programlisting>
!      (This works for any <application>libpq</>-based client application, not
!      just <application>psql</application>.) Note that this won't work for
!      parameters that are fixed when the server is started or that must be
!      specified in <filename>postgresql.conf</filename>.
!     </para>
  
!     <para>
!      Furthermore, it is possible to assign a set of parameter settings to
!      a user or a database.  Whenever a session is started, the default
!      settings for the user and database involved are loaded.  The
!      commands <xref linkend="sql-alterrole">
!      and <xref linkend="sql-alterdatabase">,
!      respectively, are used to configure these settings.  Per-database
!      settings override anything received from the
!      <command>postgres</command> command-line or the configuration
!      file, and in turn are overridden by per-user settings; both are
!      overridden by per-session settings.
      </para>
  
      <para>
!      Some parameters can be changed in individual <acronym>SQL</acronym>
!      sessions with the <xref linkend="SQL-SET">
!      command, for example:
! <screen>
! SET ENABLE_SEQSCAN TO OFF;
! </screen>
!      If <command>SET</> is allowed, it overrides all other sources of
!      values for the parameter. Some parameters cannot be changed via
!      <command>SET</command>: for example, if they control behavior that
!      cannot be changed without restarting the entire
!      <productname>PostgreSQL</productname> server.  Also, some parameters
!      require superuser permission to change via <command>SET</command> or
!      <command>ALTER</>.
      </para>
  
!     <para>
!      Another way to change configuration parameters persistently is by
!      use of <xref linkend="SQL-ALTERSYSTEM">
!      command, for example:
! <screen>
! ALTER SYSTEM SET checkpoint_timeout TO 600;
! </screen>
!      This command will allow users to change values persistently
!      through SQL command. The values will be effective after reload of server configuration
!      (<acronym>SIGHUP</>) or server startup. The effect of this command is similar to when
!      user manually changes values in <filename>postgresql.conf</filename>.
      </para>
     </sect2>
  
!    <sect2 id="config-setting-examining">
!     <title>Examining Parameter Settings</title>
  
!     <para>
!      The <xref linkend="SQL-SHOW">
!      command allows inspection of the current values of all parameters.
!     </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
!      each parameter than is available from <command>SHOW</>.
!     </para>
  
     </sect2>
  
--- 123,310 ----
  search_path = '"$user", public'
  shared_buffers = 128MB
  </programlisting>
!      One parameter is specified per line. The equal sign between name
!      and value is optional. Whitespace is insignificant and blank
!      lines are ignored. Hash marks (<literal>#</literal>) designate the
!      remainder of lines as comments.  Parameter values that are not simple
!      identifiers or numbers must be single-quoted.  To embed a single
!      quote in a parameter value, write either two quotes (preferred)
!      or backslash-quote.
!     </para>
! 
!     <para>
!      Parameters set in this way provide default values for the cluster.
!      The setting seen by active sessions will be this value unless
!      it is overridden.  The following sections describe ways in which the
!      administrator or user can override these defaults.
      </para>
  
      <para>
       <indexterm>
!        <primary>SIGHUP</primary>
       </indexterm>
       The configuration file is reread whenever the main server process
       receives a <systemitem>SIGHUP</> signal;  this is most easily done by
       running <literal>pg_ctl reload</> from the command-line or by calling
       the SQL function <function>pg_reload_conf()</function>. The main
!      server process also propagates this signal to all currently running
!      server processes so that existing sessions also get the new value
!      when they complete their transactions.  Alternatively, you can
!      send the signal to a single server process directly.  Some parameters
!      can only be set at server start; any changes to their entries in the
!      configuration file will be ignored until the server is restarted.
!      Invalid parameter settings in the configuration file are likewise
!      ignored (but logged) during <systemitem>SIGHUP</> processing.
      </para>
     </sect2>
  
!    <sect2 id="config-setting-sql-command-interaction">
!     <title>Parameter Interaction via SQL</title>
!      <para>
!        <productname>PostgreSQL</productname> provides three SQL
!        commands to establish configuration defaults that override those
!        configured globally.  The evaluation of these defaults occurs
!        at the beginning of a new session, upon the user issuing <xref
!        linkend="SQL-DISCARD">, or if the server forces the session to
!        reload its configuration after a <systemitem>SIGHUP</systemitem>
!        signal.
!      </para>
  
!      <itemizedlist>
!       <listitem>
!        <para>
!         The <xref linkend="SQL-ALTERSYSTEM"> command provides an
!         SQL-accessible means of changing global defaults.
!       </para>
!      </listitem>
  
!      <listitem>
!       <para>
!        The <xref linkend="sql-alterdatabase"> command allows database
!        administrators to override global settings on a per-database basis.
!       </para>
!      </listitem>
  
!      <listitem>
!       <para>
!        The <xref linkend="sql-alterrole"> command allows database
!        administrators to override both global and per-database settings
!        with user-specific values.
!       </para>
!      </listitem>
!     </itemizedlist>
! 
!      <para>
!       Once a client connects to the database PostgreSQL provides
!       two additional SQL commands to interact with session-local
!       configuration settings.  Both of these commands have equivalent
!       system administration functions.
      </para>
  
+     <itemizedlist>
+      <listitem>
+      <para>
+       The <xref linkend="SQL-SHOW"> command allows inspection of the
+       current value of all parameters.  The corresponding function is
+       <function>current_setting(setting_name text)</function>.
+      </para>
+      </listitem>
+ 
+      <listitem>
+       <para>
+        The <xref linkend="SQL-SET"> command allows modification of the
+        current value of some parameters.  The corresponding function is
+        <function>set_config(setting_name, new_value, is_local)</function>.
+       </para>
+      </listitem>
+     </itemizedlist>
+ 
      <para>
!      Both <command>SELECT</> and <command>UPDATE</>
!      can be issued against the system view <link
!      linkend="view-pg-settings"><structname>pg_settings</></> to view
!      and change session-local values.
      </para>
  
!     <itemizedlist>
!      <listitem>
!       <para>
!        Querying this view is the sames as <command>SHOW</> but provides
!        more detail, as well as allowing for joins against other relations
!        and the specification of filter criteria.
!       </para>
!      </listitem>
! 
!     <listitem>
!      <para>
!        Using <xref linkend="SQL-UPDATE"> on this relation, specifically
!        updating the <structname>setting</> column, is the equivalent
!        of issuing SQL <command>SET</>, though all values must be
!        single-quoted.  Note that the equivalent of
! <programlisting>
! SET configuration_parameter TO DEFAULT;
! </>
!       is:
! <programlisting>
! UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
! </programlisting>
      </para>
+     </listitem>
+    </itemizedlist>
+ 
     </sect2>
  
!    <sect2>
!     <title>Parameter Interaction via Shell</title>
!      <para>
!       In addition to setting global defaults or attaching
!       overrides at the database or role level, you can pass setting to
!       <productname>PostgreSQL</productname> via shell facilities.
!       Both the server and <application>libpq</> client library
!       accept parameter values via the shell.
!      </para>
  
!      <itemizedlist>
!       <listitem>
!       <para>
!        On the <emphasis>server</emphasis>, command-line options can be
!        passed to the <command>postgres</command> command directly via the
!        <option>-c</> parameter.
! <programlisting>
! postgres -c log_connections=yes -c log_destination='syslog'
! </programlisting>
!        Settings provided this way override those resolved globally (via
!        <filename>postgresql.conf</> or <command>ALTER SYSTEM</>) but
!        are otherwise treated as being global for the purpose of database
!        and role overrides.
!      </para>
!     </listitem>
  
!     <listitem>
!      <para>
!       On the <emphasis>libpq-client</emphasis>, command-line options can be
!       specified using the <envar>PGOPTIONS</envar> environment variable.
!       When connecting to the server, the contents of this variable are
!       sent to the server as if they were being executed via SQL <xref
!       linkend="SQL-SET"> at the beginning of the session.
!      </para>
! 
!      <para>
!       However, the format of <envar>PGOPTIONS</envar> is similar to that
!       used when launching the <command>postgres</command> command.
!       Specifically, the <option>-c</> flag must be specified.
! <programlisting>
! env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
! </programlisting>
!      </para>
! 
!      <para>
!       Other clients and libraries might provide their own mechanisms,
!       via the shell or otherwise, that allow the user to alter session
!       settings without requiring the user to issue SQL commands.
!      </para>
!     </listitem>
!    </itemizedlist>
  
     </sect2>
  

--GvXjxJ+pjyke8COw
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--GvXjxJ+pjyke8COw--