<!-- doc/src/sgml/config.sgml -->

<chapter id="runtime-config">
  <title>Server Configuration</title>

  <indexterm>
    <primary>configuration</primary>
    <secondary>of the server</secondary>
  </indexterm>

  <para>
    There are many configuration parameters that affect the behavior of
    <productname>Pgpool-II</productname>. In the first section of this chapter we
    describe how to interact with configuration parameters. The subsequent sections
    discuss each parameter in detail.
  </para>

  <sect1 id="config-setting">
    <title>Setting Parameters</title>

    <sect2 id="config-setting-names-values">
      <title>Parameter Names and Values</title>

      <para>
	All parameter names are case-insensitive. Every parameter takes a
	value of one of five types: boolean, string, integer, floating point,
	or enumerated (enum).  The type determines the syntax for setting the
	parameter:
      </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 one of these.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <emphasis>String:</emphasis>
	    In general, enclose the value in single quotes, doubling any single
	    quotes within the value.  Quotes can usually be omitted if the value
	    is a simple number or identifier, however.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <emphasis>Numeric (integer and floating point):</emphasis>
	    A decimal point is permitted only for floating-point parameters.
	    Do not use thousands separators.  Quotes are not required.
	  </para>
	</listitem>

  <listitem>
    <para>
      <emphasis>Enumerated:</emphasis>
      Enumerated-type parameters are written in the same way as string
      parameters, but are restricted to have one of a limited set of
      values. Enum parameter values are case-insensitive.
    </para>
  </listitem>
</itemizedlist>
</sect2>

<sect2 id="config-setting-configuration-file">
  <title>Parameter Interaction via the Configuration File</title>

  <para>
    The most fundamental way to set these parameters is to edit the file
    <filename>pgpool.conf</><indexterm><primary>pgpool.conf</></>,
    which is located in <literal>$prefix/etc/pgpool.conf</literal>.
    An example of what this file might look like is:
    <programlisting>
  # This is a comment
  listen_addresses = 'localhost'
  port = 9999
  serialize_accept = off
  reset_query_list = 'ABORT; DISCARD ALL'
    </programlisting>

      One parameter is specified per line. The equal sign between name and
      value is optional. Whitespace is insignificant (except within a quoted
      parameter value) 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>
      Parameters set in this way provide default values for the cluster.
      The settings seen by active sessions will be these values unless they
      are 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 signal is most easily
      sent by running <literal>pgpool reload</> from the command line. The main
      pgpool process also propagates this signal to all its child
      processes, so that existing sessions also adopt the new values.
      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 Clients</title>

  <para>
	  <productname>Pgpool-II</productname> also provides two SQL style
	  commands to interact with session-local configuration settings.
  </para>

  <itemizedlist>
    <listitem>
      <para>
	    The <xref linkend="SQL-PGPOOL-SHOW"> command allows inspection of the
	    current value of all parameters.
	    </para>
    </listitem>

    <listitem>
      <para>
	    The <xref linkend="SQL-PGPOOL-SET"> command allows modification of the
	    current value of those parameters that can be set locally to a
	    session; it has no effect on other sessions.
      </para>
    </listitem>
  </itemizedlist>

  </sect2>
</sect1>

