 <Chapter Id="trouble">
  <Title>Troubleshooting</Title>

  <sect1>
   <title>Client Connections</title>
   <Para>
    If  you get the following error message from a 
    <ProductName>Postgres</ProductName>
    command (such as <Application>psql</Application> or 
    <Application>createdb</Application>):

    <ProgramListing>
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
    </ProgramListing>

    it is usually because either the <Application>postmaster</Application> is not running,
    or you are attempting to connect to the wrong server host.
    If you get the following error message:

    <ProgramListing>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
    </ProgramListing>

    it means that the site administrator started the  <Application>postmaster</Application>
    as  the  wrong user.  Tell him to restart it as
    the <ProductName>Postgres</ProductName> superuser.
   </Para>
  </sect1>

  <sect1>
   <title>Debugging Messages</title>

   <para>
    The <Application>postmaster</Application> occasionally prints out  
    messages  which
    are  often helpful during troubleshooting.  If you wish
    to view debugging messages from the <Application>postmaster</Application>, 
    you can
    start  it with the -d option and redirect the output to
    the log file:

    <ProgramListing>
% postmaster -d >& pm.log &
    </ProgramListing>

    If you do not wish to see these messages, you can type
    <ProgramListing>
% postmaster -S
    </ProgramListing>
    and the <Application>postmaster</Application> will be "S"ilent.  
    Notice that there
    is no ampersand ("&amp") at the end of the last example so
    postmaster will be running in the foreground.
   </Para>

   <sect2 Id="pg-options-trouble">
    <Title>pg_options</Title>

    <Para>
     <Note>
      <Para>
       Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
      </Para>
     </Note>
    </para>
    <Para>
     The optional file <filename>data/pg_options</filename> contains runtime
     options used by the backend to control trace messages and other backend
     tunable parameters.
     What makes this file interesting is the fact that it is re-read by a backend
     when it receives a SIGHUP signal, making thus possible to change run-time
     options on the fly without needing to restart 
     <productname>Postgres</productname>.
     The options specified in this file may be debugging flags used by the trace
     package (<filename>backend/utils/misc/trace.c</filename>) or numeric
     parameters which can be used by the backend to control its behaviour.
     New options and parameters must be defined in
     <filename>backend/utils/misc/trace.c</filename> and
     <filename>backend/include/utils/trace.h</filename>.
    </para>

   <para>
    pg_options can also be specified with the <option>-T</option> switch of 
    <productname>Postgres</productname>:

    <programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
    </programlisting>
   </para>

   <Para>
    The functions used for printing errors and debug messages can now make use
    of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
    or stderr are prefixed by a timestamp containing also the backend pid:

    <programlisting>
#timestamp          #pid    #message
980127.17:52:14.173 [29271] StartTransactionCommand
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
980127.17:52:14.186 [29286] Async_NotifyHandler
980127.17:52:14.186 [29286] Waking up sleeping backend process
980127.19:52:14.292 [29286] Async_NotifyFrontEnd
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done
    </programlisting>
   </para>

   <para>
    This format improves readability of the logs and allows people to understand
    exactly which backend is doing what and at which time. It also makes
    easier to write simple awk or perl scripts which monitor the log to
    detect database errors or problem, or to compute transaction time statistics.
   </para>

   <para>
    Messages printed to syslog use the log facility LOG_LOCAL0.
    The use of syslog can be controlled with the syslog pg_option.
    Unfortunately many functions call directly <function>printf()</function>
    to print their messages to stdout or stderr and this output can't be
    redirected to syslog or have timestamps in it. 
    It would be advisable that all calls to printf would be replaced with the
    PRINTF macro and output to stderr be changed to use EPRINTF instead so that
    we can control all output in a uniform way.
   </Para>

    <para>
     The format of the <filename>pg_options</filename> file is as follows:

     <programlisting>
# <replaceable>comment</replaceable>
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable>  # set value for <replaceable>option</replaceable>
<replaceable>option</replaceable>                # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>+               # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>-               # set <replaceable>option</replaceable> = 0
     </programlisting>

     Note that <replaceable class="parameter">keyword</replaceable> can also be
     an abbreviation of the option name defined in
     <filename>backend/utils/misc/trace.c</filename>.
    </Para>

    <Para>
     Refer to <xref linkend="pg-options-title" endterm="pg-options-title">
     for a complete list of option keywords and possible values.
    </para>
   </sect2>
  </sect1>
 </Chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
