config.sgml

来自「PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统」· SGML 代码 · 共 1,536 行 · 第 1/5 页

<!--
$PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.36.2.6 2006/05/21 20:11:02 tgl Exp $
-->
<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
   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>

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

   <para>
    All parameter names are case-insensitive. Every parameter takes a
    value of one of four types: Boolean, integer, floating point,
    or string. Boolean values may 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>
    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. (<command>initdb</>
    installs a default copy there.) An example of what this file might look
    like is:
<programlisting>
# This is a comment
log_connections = yes
log_destination = 'syslog'
search_path = '$user, public'
</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>) introduce comments
    anywhere.  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
    <command>postmaster</command> process receives a
    <systemitem>SIGHUP</> signal (which is most easily sent by means
    of <literal>pg_ctl reload</>). The <command>postmaster</command>
    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.
   </para>

   <para>
    A second way to set these configuration parameters is to give them
    as a command line option to the <command>postmaster</command>, such as:
<programlisting>
postmaster -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 may 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 option 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-alteruser" endterm="sql-alteruser-title">
    and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">,
    respectively, are used to configure these settings.  Per-database
    settings override anything received from the
    <command>postmaster</command> command-line or the configuration
    file, and in turn are overridden by per-user settings; both are
    overridden by per-session options.
   </para>

   <para>
    Some parameters can be changed in individual <acronym>SQL</acronym>
    sessions with the <xref linkend="SQL-SET" endterm="SQL-SET-title">
    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 reasonably be changed without restarting
    <productname>PostgreSQL</productname>.  Also, some parameters can
    be modified via <command>SET</command> or <command>ALTER</> by superusers,
    but not by ordinary users.
   </para>

   <para>
    The <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title">
    command allows inspection of the current values of all parameters.
   </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
    to use because it can be joined with other tables, or selected from using
    any desired selection condition.
   </para>
  </sect1>

   <sect1 id="runtime-config-file-locations">
    <title>File Locations</title>

     <para>
      In addition to the <filename>postgresql.conf</filename> file
      already mentioned, <productname>PostgreSQL</productname> uses
      two other manually-edited configuration files, which control
      client authentication (their use is discussed in <xref
      linkend="client-authentication">).  By default, all three
      configuration files are stored in the database cluster's data
      directory.  The options described in this section allow the
      configuration files to be placed elsewhere.  (Doing so can ease
      administration.  In particular it is often easier to ensure that
      the configuration files are properly backed-up when they are
      kept separate.)
     </para>

     <variablelist>
     <varlistentry id="guc-data-directory" xreflabel="data_directory">
      <term><varname>data_directory</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>data_directory</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the directory to use for data storage.
         This option can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-config-file" xreflabel="config_file">
      <term><varname>config_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>config_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the main server configuration file
         (customarily called <filename>postgresql.conf</>).
         This option can only be set on the postmaster command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-hba-file" xreflabel="hba_file">
      <term><varname>hba_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>hba_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the configuration file for host-based authentication
         (customarily called <filename>pg_hba.conf</>).
         This option can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ident-file" xreflabel="ident_file">
      <term><varname>ident_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ident_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the configuration file for
         <application>ident</> authentication
         (customarily called <filename>pg_ident.conf</>).
         This option can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
      <term><varname>external_pid_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>external_pid_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of an additional process-id (PID) file that the
        <application>postmaster</> should create for use by server
        administration programs.
        This option can only be set at server start.
       </para>
      </listitem>
     </varlistentry>
     </variablelist>

     <para>
      In a default installation, none of the above options are set explicitly.
      Instead, the
      data directory is specified by the <option>-D</option> command-line
      option or the <envar>PGDATA</envar> environment variable, and the
      configuration files are all found within the data directory.
     </para>

     <para>
      If you wish to keep the configuration files elsewhere than the
      data directory, the postmaster's <option>-D</option>
      command-line option or <envar>PGDATA</envar> environment variable
      must point to the directory containing the configuration files,
      and the <varname>data_directory</> option must be set in
      <filename>postgresql.conf</filename> (or on the command line) to show
      where the data directory is actually located.  Notice that
      <varname>data_directory</> overrides <option>-D</option> and
      <envar>PGDATA</envar> for the location
      of the data directory, but not for the location of the configuration
      files.
     </para>

     <para>
      If you wish, you can specify the configuration file names and locations
      individually using the options <varname>config_file</>,
      <varname>hba_file</> and/or <varname>ident_file</>.
      <varname>config_file</> can only be specified on the 
      <command>postmaster</command> command line, but the others can be
      set within the main configuration file.  If all three options plus
      <varname>data_directory</> are explicitly set, then it is not necessary
      to specify <option>-D</option> or <envar>PGDATA</envar>.
     </para>

     <para>
      When setting any of these options, a relative path will be interpreted
      with respect to the directory in which the <command>postmaster</command>
      is started.
     </para>
   </sect1>

   <sect1 id="runtime-config-connection">
    <title>Connections and Authentication</title>

    <sect2 id="runtime-config-connection-settings">
     <title>Connection Settings</title>

     <variablelist>

     <varlistentry id="guc-listen-addresses" xreflabel="listen_addresses">
      <term><varname>listen_addresses</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>listen_addresses</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the TCP/IP address(es) on which the server is
         to listen for connections from client applications.  
         The value takes the form of a comma-separated list of host names
         and/or numeric IP addresses.  The special entry <literal>*</>
         corresponds to all available IP interfaces.
         If the list is empty, the server does not listen on any IP interface
         at all, in which case only Unix-domain sockets can be used to connect
         to it.
         The default value is <systemitem class="systemname">localhost</>,
         which allows only local <quote>loopback</> connections to be made.
         This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-port" xreflabel="port">
      <term><varname>port</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>port</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        The TCP port the server listens on; 5432 by default.  Note that the
        same port number is used for all IP addresses the server listens on.
        This parameter can only be set at server start.