Bug Reporting Guidelines {#bug-reporting}
========================

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.

Identifying Bugs
----------------

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 process.

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.

What to Report
--------------

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 way to create 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
    > [???](#guc-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
    `postgres --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 might
    have. If you are talking about a Git snapshot, mention that,
    including the commit hash.

    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 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 x86\_64. 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. Here is an
[article](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) that
outlines some more tips on reporting bugs.

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 process,
mention that, do not just say "PostgreSQL crashes". A crash of a single
backend process is quite different from crash of the parent "postgres"
process; please don\'t say "the server 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.

Where to Report Bugs
--------------------

In general, send bug reports to the bug report mailing list at
<pgsql-bugs@lists.postgresql.org>. 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](https://www.postgresql.org/). Entering a bug
report this way causes it to be mailed to the
<pgsql-bugs@lists.postgresql.org> 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
<security@postgresql.org>.

Do not send bug reports to any of the user mailing lists, such as
<pgsql-sql@lists.postgresql.org> or
<pgsql-general@lists.postgresql.org>. 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
<pgsql-hackers@lists.postgresql.org>. 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 <pgsql-docs@lists.postgresql.org>.
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 <pgsql-hackers@lists.postgresql.org>, so we (and you) can work
on porting PostgreSQL to your platform.

> **Note**
>
> Due to the unfortunate amount of spam going around, all of the above
> lists will be moderated unless you are subscribed. That means there
> will be some delay before the email is delivered. If you wish to
> subscribe to the lists, please visit [](https://lists.postgresql.org/)
> for instructions.
