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

<sect1 id="bug-reporting">
 <title>Bug Reporting Guidelines</title>

 <para>
  When you find a bug in <productname>PostgreSQL</productname> we want to
  hear about it. Your bug reports play an important part in making
  <productname>PostgreSQL</productname> more reliable because even the utmost
  care cannot guarantee that every part of
  <productname>PostgreSQL</productname>
  will work on every platform under every circumstance.
 </para>

 <para>
  The following suggestions are intended to assist you in forming bug reports
  that can be handled in an effective fashion. No one is required to follow
  them but doing so tends to be to everyone's advantage.
 </para>

 <para>
  We cannot promise to fix every bug right away. If the bug is obvious, critical,
  or affects a lot of users, chances are good that someone will look into it. It
  could also happen that we tell you to update to a newer version to see if the
  bug happens there. Or we might decide that the bug
  cannot be fixed before some major rewrite we might be planning is done. Or
  perhaps it is simply too hard and there are more important things on the agenda.
  If you need help immediately, consider obtaining a commercial support contract.
 </para>

 <sect2 id="bug-reporting-identifying-bugs">
  <title>Identifying Bugs</title>

  <para>
   Before you report a bug, please read and re-read the
   documentation to verify that you can really do whatever it is you are
   trying. If it is not clear from the documentation whether you can do
   something or not, please report that too; it is a bug in the documentation.
   If it turns out that a program does something different from what the
   documentation says, that is a bug. That might include, but is not limited to,
   the following circumstances:

   <itemizedlist>
    <listitem>
     <para>
      A program terminates with a fatal signal or an operating system
      error message that would point to a problem in the program. (A
      counterexample might be a <quote>disk full</quote> message,
      since you have to fix that yourself.)
     </para>
    </listitem>

    <listitem>
     <para>
      A program produces the wrong output for any given input.
     </para>
    </listitem>

    <listitem>
     <para>
      A program refuses to accept valid input (as defined in the documentation).
     </para>
    </listitem>

    <listitem>
     <para>
      A program accepts invalid input without a notice or error message.
      But keep in mind that your idea of invalid input might be our idea of
      an extension or compatibility with traditional practice.
     </para>
    </listitem>

    <listitem>
     <para>
      <productname>PostgreSQL</productname> fails to compile, build, or
      install according to the instructions on supported platforms.
     </para>
    </listitem>
   </itemizedlist>

   Here <quote>program</quote> refers to any executable, not only the backend process.
  </para>

  <para>
   Being slow or resource-hogging is not necessarily a bug. Read the
   documentation or ask on one of the mailing lists for help in tuning your
   applications. Failing to comply to the <acronym>SQL</acronym> standard is
   not necessarily a bug either, unless compliance for the
   specific feature is explicitly claimed.
  </para>

  <para>
   Before you continue, check on the TODO list and in the FAQ to see if your bug is
   already known. If you cannot decode the information on the TODO list, report your
   problem. The least we can do is make the TODO list clearer.
  </para>
 </sect2>

 <sect2 id="bug-reporting-what-to-report">
  <title>What to Report</title>

  <para>
   The most important thing to remember about bug reporting is to state all
   the facts and only facts. Do not speculate what you think went wrong, what
   <quote>it seemed to do</quote>, or which part of the program has a fault.
   If you are not familiar with the implementation you would probably guess
   wrong and not