<Sect1>

<title>Bug Reporting Guidelines</title>

<para>

When you encounter a bug 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 <quote>Is this a bug?</quote>, 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 (for

example not <quote>disk full</quote>).

</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 <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 <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

<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 doesn't matter or the report would <quote>ring a bell</quote>

anyway.

</para>

<para>

The following items should be contained in every bug report:

<itemizedlist>

<listitem>

<para>

The exact sequence of steps <emphasis>from program startup</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> startup 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

<quote>large files</quote> or <quote>mid-size databases</quote>, etc.

</para>

</listitem>

<listitem>

<para>

The output you got. Please do not say that it <quote>didn't work</quote> or

<quote>failed</quote>. 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

<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 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 <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 startup 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 PostgreSQL version. You can run the command

<literal>SELECT version();</literal> to

find out. 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 6.5 we will almost certainly tell you to upgrade. There are tons

of bugs in old versions, that's why we write new ones.

</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

<quote>Debian</quote> 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 <quote>PostgreSQL</quote>,

sometimes <quote>Postgres</quote> for short. (Sometimes

the abbreviation <quote>Pgsql</quote> is used but don't do that.) When you

are specifically talking about the backend server, mention that, don't

just say <quote>Postgres crashes</quote>. The interactive frontend is called

<quote>psql</quote> 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 &lt;pgsql-bugs@postgresql.org&gt;. 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

pgsql-sql or pgsql-general. These mailing lists are for answering

user questions, 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

&lt;pgsql-hackers@postgresql.org&gt;. This list is for discussing the

development of <productname>PostgreSQL</productname>, it would be nice

if we could keep the bug reports separate. We might choose 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

&lt;pgsql-docs@postgresql.org&gt;. Refer to the document, chapter, and sections.

</para>

<para>

If your bug is a portability problem on a non-supported platform, send

mail to &lt;pgsql-ports@postgresql.org&gt;, 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 <quote>list</quote>, which

allows you to post to all <productname>PostgreSQL</productname>

mailing lists without receiving any messages. Send email to

&lt;pgsql-loophole-request@postgresql.org&gt; to subscribe.

</para>

</note>

</Sect2>

</Sect1>