runtime.sgml

PostgreSQL7.4.6 for Linux

</screen>
    </para>

    <para>
     A message like
<screen>
FATAL:  could not create shared memory segment: Invalid argument
DETAIL:  Failed system call was shmget(key=5440001, size=4011376640, 03600).
</screen>
     probably means your kernel's limit on the size of shared memory is
     smaller than the work area <productname>PostgreSQL</productname>
     is trying to create (4011376640 bytes in this example). Or it could
     mean that you do not have System-V-style shared memory support
     configured into your kernel at all. As a temporary workaround, you
     can try starting the server with a smaller-than-normal number
     of buffers (<option>-B</option> switch). You will eventually want
     to reconfigure your kernel to increase the allowed shared memory
     size. You may also see this message when trying to start multiple
     servers on the same machine, if their total space requested
     exceeds the kernel limit.
    </para>

    <para>
     An error like
<screen>
FATAL:  could not create semaphores: No space left on device
DETAIL:  Failed system call was semget(5440126, 17, 03600).
</screen>
     does <emphasis>not</emphasis> mean you've run out of disk
     space. It means your kernel's limit on the number of <systemitem
     class="osname">System V</> semaphores is smaller than the number
     <productname>PostgreSQL</productname> wants to create. As above,
     you may be able to work around the problem by starting the
     server with a reduced number of allowed connections
     (<option>-N</option> switch), but you'll eventually want to
     increase the kernel limit.
    </para>

    <para>
     If you get an <quote>illegal system call</> error, it is likely that
     shared memory or semaphores are not supported in your kernel at
     all. In that case your only option is to reconfigure the kernel to
     enable these features.
    </para>

    <para>
     Details about configuring <systemitem class="osname">System V</>
     <acronym>IPC</> facilities are given in <xref linkend="sysvipc">.
    </para>
   </sect2>

   <sect2 id="client-connection-problems">
    <title>Client Connection Problems</title>

    <para>
     Although the error conditions possible on the client side are quite
     varied and application-dependent, a few of them might be directly
     related to how the server was started up. Conditions other than
     those shown below should be documented with the respective client
     application.
    </para>

    <para>
<screen>
psql: could not connect to server: Connection refused
        Is the server running on host "server.joe.com" and accepting
        TCP/IP connections on port 5432?
</screen>
     This is the generic <quote>I couldn't find a server to talk
     to</quote> failure. It looks like the above when TCP/IP
     communication is attempted. A common mistake is to forget to
     configure the server to allow TCP/IP connections.
    </para>

    <para>
     Alternatively, you'll get this when attempting Unix-domain socket
     communication to a local server:
<screen>
psql: could not connect to server: No such file or directory
        Is the server running locally and accepting
        connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
</screen>
    </para>

    <para>
     The last line is useful in verifying that the client is trying to
     connect to the right place. If there is in fact no server
     running there, the kernel error message will typically be either
     <computeroutput>Connection refused</computeroutput> or
     <computeroutput>No such file or directory</computeroutput>, as
     illustrated. (It is important to realize that
     <computeroutput>Connection refused</computeroutput> in this context
     does <emphasis>not</emphasis> mean that the server got your
     connection request and rejected it. That case will produce a
     different message, as shown in <xref
     linkend="client-authentication-problems">.) Other error messages
     such as <computeroutput>Connection timed out</computeroutput> may
     indicate more fundamental problems, like lack of network
     connectivity.
    </para>
   </sect2>
  </sect1>

  <sect1 id="runtime-config">
   <Title>Run-time Configuration</Title>

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

   <para>
    There are a lot of configuration parameters that affect the
    behavior of the database system. In this subsection, we describe
    how to set configuration parameters; the following subsections
    discuss each parameter in detail.
   </para>

   <para>
    All parameter names are case-insensitive. Every parameter takes a
    value of one of the four types: boolean, integer, floating point,
    and string. Boolean values are <literal>ON</literal>,
    <literal>OFF</literal>, <literal>TRUE</literal>,
    <literal>FALSE</literal>, <literal>YES</literal>,
    <literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
    (case-insensitive) or any non-ambiguous prefix of these.
   </para>

   <para>
    One way to set these parameters is to edit the file
    <filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</></>
    in the data directory. (A default file is installed there.) An
    example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
syslog = 2
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 should be single-quoted.
   </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.
   </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 syslog=2
</programlisting>
    Command-line options override any conflicting settings in
    <filename>postgresql.conf</filename>.
   </para>

   <para>
    Occasionally it is also 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, such as the port
    number.
   </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 <command>ALTER DATABASE</command> and <command>ALTER
    USER</command>, 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.  Superusers are allowed to <command>SET</>
    more values than 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>
    
   <sect2 id="runtime-config-connection">
    <title>Connections and Authentication</title>

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

     <variablelist>
     
     <varlistentry>
      <term><varname>tcpip_socket</varname> (<type>boolean</type>)</term>
      <listitem>
       <para>
        If this is true, then the server will accept TCP/IP connections.<indexterm><primary>TCP/IP</></>
        Otherwise only local Unix domain socket connections are
        accepted. It is off by default. This option can only be set at
        server start.
       </para>
      </listitem>
     </varlistentry>
  
     <varlistentry>
      <term><varname>max_connections</varname> (<type>integer</type>)</term>
      <listitem>
       <para>
        Determines the maximum number of concurrent connections to the
        database server. The default is typically 100, but may be less
        if your kernel settings will not support it (as determined
        during <application>initdb</>).  This parameter can only be
        set at server start.
       </para>

       <para>
        Increasing this parameter may cause <productname>PostgreSQL</>
        to request more <systemitem class="osname">System V</> shared
        memory or semaphores than your operating system's default configuration
        allows. See <xref linkend="sysvipc"> for information on how to
        adjust these parameters, if necessary.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><varname>superuser_reserved_connections</varname>
      (<type>integer</type>)</term>
      <listitem>
       <para>
        Determines the number of <quote>connection slots</quote> that
        are reserved for connections by <productname>PostgreSQL</>
        superusers.  At most <varname>max_connections</> connections can
        ever be active simultaneously.  Whenever the number of active
        concurrent connections is at least <varname>max_connections</> minus
        <varname>superuser_reserved_connections</varname>, new connections
        will be accepted only for superusers.
       </para>

       <para>
        The default value is 2. The value must be less than the value of
        <varname>max_connections</varname>. This parameter can only be
        set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><varname>port</varname> (<type>integer</type>)</term>
      <indexterm><primary>port</></>
      <listitem>
       <para>
        The TCP port the server listens on; 5432 by default. This
        option can only be set at server start.
       </para>
      </listitem>
     </varlistentry>


     <varlistentry>
      <term><varname>unix_socket_directory</varname> (<type>string</type>)</term>
      <listitem>
       <para>
        Specifies the directory of the Unix-domain socket on which the
        server is to listen for
        connections from client applications.  The default is normally
        <filename>/tmp</filename>, but can be changed at build time.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><varname>unix_socket_group</varname> (<type>string</type>)</term>
      <listitem>
       <para>
        Sets the group owner of the Unix domain socket.  (The owning
        user of the socket is always the user that starts the
        server.)  In combination with the option
        <varname>unix_socket_permissions</varname> this can be used as
        an additional access control mechanism for this socket type.
        By default this is the empty string, which uses the default
        group for the current user.  This option can only be set at
        server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><varname>unix_socket_permissions</varname> (<type>integer</type>)</term>
      <listitem>
       <para>
        Sets the access permissions of the Unix domain socket.  Unix
        domain sockets use the usual Unix file system permission set.
        The option value is expected to be an numeric mode
        specification in the form accepted by the
        <function>chmod</function> and <function>umask</function>
        system calls.  (To use the customary octal format the number
        must start with a <literal>0</literal> (zero).)
       </para>

       <para>