mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-30 01:57:19 +02:00
where appropriate. Add "id" and "xreflabel" tags to the descriptions of the GUC variables to facilitate this. Also make a few minor docs cleanups.
378 lines
15 KiB
Plaintext
378 lines
15 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/problems.sgml,v 2.18 2004/03/09 16:57:46 neilc 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
|
|
think it looks OK and is exactly what we expected. We should not have to
|
|
spend the time to decode the exact semantics behind your commands.
|
|
Especially refrain from merely saying that <quote>This is not what SQL says/Oracle
|
|
does.</quote> Digging out the correct behavior from <acronym>SQL</acronym>
|
|
is not a fun undertaking, nor do we all know how all the other relational
|
|
databases out there behave. (If your problem is a program crash, you can
|
|
obviously omit this item.)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Any command line options and other start-up options, including
|
|
any relevant environment variables or configuration files that
|
|
you changed from the default. Again, please provide exact
|
|
information. If you are using a prepackaged distribution that
|
|
starts the database server at boot time, you should try to find
|
|
out how that is done.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Anything you did at all differently from the installation
|
|
instructions.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The <productname>PostgreSQL</productname> version. You can run the command
|
|
<literal>SELECT version();</literal> to
|
|
find out the version of the server you are connected to. Most executable
|
|
programs also support a <option>--version</option> option; at least
|
|
<literal>postmaster --version</literal> and <literal>psql --version</literal>
|
|
should work.
|
|
If the function or the options do not exist then your version is
|
|
more than old enough to warrant an upgrade.
|
|
If you run a prepackaged version, such as RPMs, say so, including any
|
|
subversion the package may have. If you are talking about a CVS
|
|
snapshot, mention that, including its date and time.
|
|
</para>
|
|
|
|
<para>
|
|
If your version is older than &version; we will almost certainly
|
|
tell you to upgrade. There are many bug fixes and improvements
|
|
in each new release, so it is quite possible that a bug you have
|
|
encountered in an older release of <productname>PostgreSQL</>
|
|
has already been fixed. We can only provide limited support for
|
|
sites using older releases of PostgreSQL; if you require more
|
|
than we can provide, consider acquiring a commercial support
|
|
contract.
|
|
</para>
|
|
<para>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Platform information. This includes the kernel name and version,
|
|
C library, processor, memory information, and so on. In most
|
|
cases it is sufficient to report the vendor and version, but do
|
|
not assume everyone knows what exactly <quote>Debian</quote>
|
|
contains or that everyone runs on Pentiums. If you have
|
|
installation problems then information about the toolchain on
|
|
your machine (compiler, <application>make</application>, and so
|
|
on) is also necessary.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
|
|
It is better to report everything the first time than us having to squeeze the
|
|
facts out of you. On the other hand, if your input files are huge, it is
|
|
fair to ask first whether somebody is interested in looking into it.
|
|
</para>
|
|
|
|
<para>
|
|
Do not spend all your time to figure out which changes in the input make
|
|
the problem go away. This will probably not help solving it. If it turns
|
|
out that the bug cannot be fixed right away, you will still have time to
|
|
find and share your work-around. Also, once again, do not waste your time
|
|
guessing why the bug exists. We will find that out soon enough.
|
|
</para>
|
|
|
|
<para>
|
|
When writing a bug report, please avoid confusing terminology.
|
|
The software package in total is called <quote>PostgreSQL</quote>,
|
|
sometimes <quote>Postgres</quote> for short. If you
|
|
are specifically talking about the backend server, mention that, do not
|
|
just say <quote>PostgreSQL crashes</quote>. A crash of a single
|
|
backend server process is quite different from crash of the parent
|
|
<quote>postmaster</> process; please don't say <quote>the postmaster
|
|
crashed</> when you mean a single backend process went down, nor vice versa.
|
|
Also, client programs such as the interactive frontend <quote><application>psql</application></quote>
|
|
are completely separate from the backend. Please try to be specific
|
|
about whether the problem is on the client or server side.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Where to report bugs</title>
|
|
|
|
<para>
|
|
In general, send bug reports to the bug report mailing list at
|
|
<email>pgsql-bugs@postgresql.org</email>.
|
|
You are requested to use a descriptive subject for your email
|
|
message, perhaps parts of the error message.
|
|
</para>
|
|
|
|
<para>
|
|
Another method is to fill in the bug report web-form available
|
|
at the project's web site
|
|
<ulink url="http://www.postgresql.org/">http://www.postgresql.org/</ulink>.
|
|
Entering a bug report this way causes it to be mailed to the
|
|
<email>pgsql-bugs@postgresql.org</email> mailing list.
|
|
</para>
|
|
|
|
<para>
|
|
Do not send bug reports to any of the user mailing lists, such as
|
|
<email>pgsql-sql@postgresql.org</email> or
|
|
<email>pgsql-general@postgresql.org</email>.
|
|
These mailing lists are for answering
|
|
user questions, and their subscribers normally do not wish to receive
|
|
bug reports. More importantly, they are unlikely to fix them.
|
|
</para>
|
|
|
|
<para>
|
|
Also, please do <emphasis>not</emphasis> send reports to
|
|
the developers' mailing list <email>pgsql-hackers@postgresql.org</email>.
|
|
This list is for discussing the
|
|
development of <productname>PostgreSQL</productname>, and it would be nice
|
|
if we could keep the bug reports separate. We might choose to take up a
|
|
discussion
|
|
about your bug report on <literal>pgsql-hackers</literal>, if the problem needs more review.
|
|
</para>
|
|
|
|
<para>
|
|
If you have a problem with the documentation, the best place to report it
|
|
is the documentation mailing list <email>pgsql-docs@postgresql.org</email>.
|
|
Please be specific about what part of the documentation you are unhappy
|
|
with.
|
|
</para>
|
|
|
|
<para>
|
|
If your bug is a portability problem on a non-supported platform,
|
|
send mail to <email>pgsql-ports@postgresql.org</email>,
|
|
so we (and you) can work on
|
|
porting <productname>PostgreSQL</productname> to your platform.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Due to the unfortunate amount of spam going around, all of the above
|
|
email addresses are closed mailing lists. That is, you need to be
|
|
subscribed to a list to be allowed to post on it. (You need not be
|
|
subscribed to use the bug-report web form, however.)
|
|
If you would like to send mail but do not want to receive list traffic,
|
|
you can subscribe and set your subscription option to <literal>nomail</>.
|
|
For more information send mail to
|
|
<email>majordomo@postgresql.org</email>
|
|
with the single word <literal>help</> in the body of the message.
|
|
</para>
|
|
</note>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- 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:
|
|
-->
|