<!--$PostgreSQL: pgsql/doc/src/sgml/problems.sgml,v 2.24 2005/04/09 03:52:43 momjian Exp $--><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>  <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 server.  </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>  <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 help us a bit. And even if you are, educated explanations are   a great supplement to but no substitute for facts. If we are going to fix   the bug we still have to see it happen for ourselves first.   Reporting the bare facts   is relatively straightforward (you can probably copy and paste them from the   screen) but all too often important details are left out because someone   thought it does not matter or the report would be understood   anyway.  </para>  <para>   The following items should be contained in every bug report:   <itemizedlist>    <listitem>     <para>      The exact sequence of steps <emphasis>from program      start-up</emphasis> necessary to reproduce the problem. This      should be self-contained; it is not enough to send in a bare      <command>SELECT</command> statement without the preceding      <command>CREATE TABLE</command> and <command>INSERT</command>      statements, if the output should depend on the data in the      tables. We do not have the time to reverse-engineer your      database schema, and if we are supposed to make up our own data      we would probably miss the problem.     </para>     <para>      The best format for a test case for SQL-related problems is a      file that can be run through the <application>psql</application>      frontend that shows the problem. (Be sure to not have anything      in your <filename>~/.psqlrc</filename> start-up file.)  An easy      start at this file is to use <application>pg_dump</application>      to dump out the table declarations and data needed to set the      scene, then add the problem query.  You are encouraged to      minimize the size of your example, but this is not absolutely      necessary.  If the bug is reproducible, we will find it either      way.     </para>     <para>      If your application uses some other client interface, such as <application>PHP</>, then      please try to isolate the offending queries. We will probably not set up a      web server to reproduce your problem. In any case remember to provide      the exact input files; do not guess that the problem happens for      <quote>large files</quote> or <quote>midsize databases</quote>, etc. since this      information is too inexact to be of use.     </para>    </listitem>    <listitem>     <para>      The output you got. Please do not say that it <quote>didn't work</quote> or      <quote>crashed</quote>. If there is an error message,      show it, even if you do not understand it. If the program terminates with      an operating system error, say which. If nothing at all happens, say so.      Even if the result of your test case is a program crash or otherwise obvious      it might not happen on our platform. The easiest thing is to copy the output      from the terminal, if possible.     </para>     <note>      <para>       If you are reporting an error message, please obtain the most verbose       form of the message.  In <application>psql</>, say <literal>\set       VERBOSITY verbose</> beforehand.  If you are extracting the message       from the server log, set the run-time parameter       <xref linkend="guc-log-error-verbosity"> to <literal>verbose</> so that all       details are logged.      </para>     </note>     <note>      <para>       In case of fatal errors, the error message reported by the client might       not contain all the information available. Please also look at the       log output of the database server. If you do not keep your server's log       output, this would be a good time to start doing so.      </para>     </note>    </listitem>    <listitem>     <para>      The output you expected is very important to state. If you just write      <quote>This command gives me that output.</quote> or <quote>This is not      what I expected.</quote>, we might run it ourselves, scan the output, and