problems.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<!--
$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