mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 20:53:23 +02:00
332 lines
13 KiB
Plaintext
332 lines
13 KiB
Plaintext
<sect1 id="problem-reporting">
|
|
<title>Problem Reporting Guidelines</title>
|
|
|
|
<para>
|
|
When you encounter a problem in <productname>PostgreSQL</productname> we want to
|
|
hear about it. Your bug reports are an important part in making
|
|
<productname>PostgreSQL</productname> more reliable because even the utmost
|
|
care cannot guarantee that every part of PostgreSQL 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 it 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's 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 ask "Is this 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's a bug in the documentation.
|
|
If it turns out that the program does something different from what the
|
|
documentation says, that's 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 "disk full" message,
|
|
since that must be fixed outside of <productname>Postgres</productname>).
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
A program accepts invalid input without a notice or error message.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<productname>PostgreSQL</productname> fails to compile, build, or
|
|
install according to the instructions on supported platforms.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Here "<literal>program</literal>" 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 <acronym>SQL</acronym> is not a bug 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 can't 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
|
|
"it seemed to do", 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 doesn't 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 select statement without the
|
|
preceeding create table and insert statements, if the output should
|
|
depend on the data in the tables. We do not have the time
|
|
to decode your database schema, and if we are supposed to make up
|
|
our own data we would probably miss the problem.
|
|
The best format for a test case for
|
|
query-language 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.) You are encouraged to
|
|
minimize the size of your example, but this is not absolutely necessary.
|
|
If the bug is reproduceable, we'll find it either way.
|
|
</para>
|
|
<para>
|
|
If your application uses some other client interface, such as PHP, then
|
|
please try to isolate the offending queries. We probably won't 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
|
|
"large files" or "mid-size databases", 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 "didn't work" or
|
|
"failed". If there is an error message,
|
|
show it, even if you don't 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>
|
|
In case of fatal errors, the error message provided by the client might
|
|
not contain all the information available. In that case, also look at the
|
|
output of the database server. If you do not keep your server 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
|
|
"This command gives me that output." or "This is not
|
|
what I expected.", we might run it ourselves, scan the output, and
|
|
think it looks okay and is exactly what we expected. We shouldn't have to
|
|
spend the time to decode the exact semantics behind your commands.
|
|
Especially refrain from merely saying that "This is not what SQL says/Oracle
|
|
does." 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 concerned
|
|
environment variables or configuration files that you changed from the
|
|
default. Again, be exact. If you are using a pre-packaged
|
|
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 what version you are currently running.
|
|
If this function does not exist, say so, then we know that
|
|
your version is old enough. If you can't start up the server or a
|
|
client, look into the README file in the source directory or at the
|
|
name of your distribution file or package name. If your version is older
|
|
than 7.0 we will almost certainly tell you to upgrade. There are tons
|
|
of bug fixes in each new version, that's why we write them.
|
|
</para>
|
|
<para>
|
|
If you run a pre-packaged 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>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Platform information. This includes the kernel name and version, C library,
|
|
processor, memory information. In most cases it is sufficient to report
|
|
the vendor and version, but do not assume everyone knows what exactly
|
|
"Debian" contains or that everyone runs on Pentiums. If
|
|
you have installation problems information about compilers, make, etc.
|
|
is also necessary.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
|
|
It's 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 can't 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'll find that out soon enough.
|
|
</para>
|
|
|
|
<para>
|
|
When writing a bug report, please choose non-confusing terminology.
|
|
The software package as such is called "PostgreSQL",
|
|
sometimes "Postgres" for short. (Sometimes
|
|
the abbreviation "Pgsql" is used but don't do that.) When you
|
|
are specifically talking about the backend server, mention that, don't
|
|
just say "Postgres crashes". The interactive frontend is called
|
|
"psql" and is for all intends and purposes completely separate
|
|
from the backend.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Where to report bugs</title>
|
|
|
|
<para>
|
|
In general, send bug reports to
|
|
<ulink url="mailto:pgsql-bugs@postgresql.org">the bug report
|
|
mailing list</ulink>.
|
|
You are invited to find a descriptive subject for your email
|
|
message, perhaps parts of the error message.
|
|
</para>
|
|
|
|
<para>
|
|
Do not send bug reports to any of the user mailing lists, such as
|
|
|
|
<ulink url="mailto:pgsql-sql@postgresql.org">the SQL language
|
|
mailing list</ulink>
|
|
or
|
|
<ulink url="mailto:pgsql-general@postgresql.org">the general topics
|
|
mailing list</ulink>.
|
|
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
|
|
<ulink url="mailto:pgsql-hackers@postgresql.org">the developers'
|
|
mailing list</ulink>.
|
|
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 it, if the bug needs more review.
|
|
</para>
|
|
|
|
<para>
|
|
If you have a problem with the documentation, send email to
|
|
<ulink url="mailto:pgsql-docs@postgresql.org">the documentation
|
|
mailing list</ulink>.
|
|
Mention the document, chapter, and sections in your problem report.
|
|
</para>
|
|
|
|
<para>
|
|
If your bug is a portability problem on a non-supported platform,
|
|
send mail to
|
|
<ulink url="mailto:pgsql-ports@postgresql.org">the porting issues mail list</ulink>,
|
|
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 them in order to be allowed to post. If you simply
|
|
want to send mail but do not want to receive list traffic, you can
|
|
subscribe to the special pgsql-loophole mailing list, which
|
|
allows you to post to all <productname>PostgreSQL</productname>
|
|
mailing lists without receiving any messages. Send email to
|
|
<ulink url="mailto:pgsql-loophole-request@postgresql.org">pgsql-loophole-request@postgresql.org</ulink>
|
|
to subscribe.
|
|
</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:
|
|
-->
|