|
When you find a bug in PostgreSQL we want to hear about it. Your bug reports play an important part in making PostgreSQL more reliable because even the utmost care cannot guarantee that every part of PostgreSQL will work on every platform under every circumstance.
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.
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.
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: 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 you have to fix that yourself.) A program produces the wrong output for any given input. A program refuses to accept valid input (as defined in the documentation).
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. PostgreSQL fails to compile, build, or install according to the instructions on supported platforms.
Here "program" refers to any executable, not only the backend server.
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 SQL standard is not necessarily a bug either, unless compliance for the specific feature is explicitly claimed.
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.
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 does not matter or the report would be understood
anyway. The following items should be contained in every bug report: The exact sequence of steps from program start-up necessary to reproduce the problem. This should be self-contained; it is not enough to send in a bare SELECT statement without the preceding CREATE TABLE and INSERT
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. The best format for a test case for SQL-related problems is a file that can be run through the psql frontend that shows the problem. (Be sure to not have anything in your ~/.psqlrc start-up file.) An easy start at this file is to use pg_dump
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. If your application uses some other client interface, such as 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 "large files" or "midsize databases", etc. since this information is too inexact to be of use. The output you got. Please do not say that it "didn't work" or "crashed".
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. Note: If you are reporting an error message, please obtain the most verbose form of the message. In psql, say \set VERBOSITY verbose beforehand. If you are extracting the message from the server log, set the run-time parameter http://www.postgresql.org/docs/8.0/static/runtime-config.html#GUC-LOG-ERROR-VERBOSITY - log_error_verbosity to verbose so that all details are logged.
Note:
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.
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 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 "This is not what SQL says/Oracle does." Digging out the correct behavior from SQL
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.) 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. Anything you did at all differently from the installation instructions. The PostgreSQL version. You can run the command SELECT version(); to find out the version of the server you are connected to. Most executable programs also support a --version option; at least postmaster --version and psql --version
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. If your version is older
than 8.0.12 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 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.
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 "Debian" contains or
that everyone runs on Pentiums. If you have installation problems then
information about the toolchain on your machine (compiler, make, and so on) is also necessary.
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. 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. When writing a bug report, please avoid confusing terminology. The software package in total is called "PostgreSQL", sometimes "Postgres" for short. If you are specifically talking about the backend server, mention that, do not just say "PostgreSQL crashes". A crash of a single backend server process is quite different from crash of the parent "postmaster" process; please don't say "the postmaster crashed" when you mean a single backend process went down, nor vice versa. Also, client programs such as the interactive frontend "psql"
are completely separate from the backend. Please try to be specific
about whether the problem is on the client or server side. In general, send bug reports to the bug report mailing list at < mailto:[email protected] - [email protected] >. You are requested to use a descriptive subject for your email message, perhaps parts of the error message. Another method is to fill in the bug report web-form available at the project's web site http://www.postgresql.org/ - http://www.postgresql.org/ . Entering a bug report this way causes it to be mailed to the < mailto:[email protected] - [email protected] > mailing list.
If your bug report has security implications and you'd prefer that it
not become immediately visible in public archives, don't send it to pgsql-bugs. Security issues can be reported privately to < mailto:[email protected] - [email protected] >. Do not send bug reports to any of the user mailing lists, such as < mailto:[email protected] - [email protected] > or < mailto:[email protected] - [email protected] >.
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. Also, please do not send reports to the developers' mailing list < mailto:[email protected] - [email protected] >. This list is for discussing the development of PostgreSQL,
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 pgsql-hackers, if the problem needs more review. If you have a problem with the documentation, the best place to report it is the documentation mailing list < mailto:[email protected] - [email protected] >. Please be specific about what part of the documentation you are unhappy with. If your bug is a portability problem on a non-supported platform, send mail to < mailto:[email protected] - [email protected] >, so we (and you) can work on porting PostgreSQL to your platform.
|