begriffs open source - ai-pg/blob - full-docs/txt/bug-reporting.txt

   1
   2 5. Bug Reporting Guidelines #
   3
   4    5.1. Identifying Bugs
   5    5.2. What to Report
   6    5.3. Where to Report Bugs
   7
   8    When you find a bug in PostgreSQL we want to hear about it. Your bug
   9    reports play an important part in making PostgreSQL more reliable
  10    because even the utmost care cannot guarantee that every part of
  11    PostgreSQL will work on every platform under every circumstance.
  12
  13    The following suggestions are intended to assist you in forming bug
  14    reports that can be handled in an effective fashion. No one is required
  15    to follow them but doing so tends to be to everyone's advantage.
  16
  17    We cannot promise to fix every bug right away. If the bug is obvious,
  18    critical, or affects a lot of users, chances are good that someone will
  19    look into it. It could also happen that we tell you to update to a
  20    newer version to see if the bug happens there. Or we might decide that
  21    the bug cannot be fixed before some major rewrite we might be planning
  22    is done. Or perhaps it is simply too hard and there are more important
  23    things on the agenda. If you need help immediately, consider obtaining
  24    a commercial support contract.
  25
  26 5.1. Identifying Bugs #
  27
  28    Before you report a bug, please read and re-read the documentation to
  29    verify that you can really do whatever it is you are trying. If it is
  30    not clear from the documentation whether you can do something or not,
  31    please report that too; it is a bug in the documentation. If it turns
  32    out that a program does something different from what the documentation
  33    says, that is a bug. That might include, but is not limited to, the
  34    following circumstances:
  35      * A program terminates with a fatal signal or an operating system
  36        error message that would point to a problem in the program. (A
  37        counterexample might be a “disk full” message, since you have to
  38        fix that yourself.)
  39      * A program produces the wrong output for any given input.
  40      * A program refuses to accept valid input (as defined in the
  41        documentation).
  42      * A program accepts invalid input without a notice or error message.
  43        But keep in mind that your idea of invalid input might be our idea
  44        of an extension or compatibility with traditional practice.
  45      * PostgreSQL fails to compile, build, or install according to the
  46        instructions on supported platforms.
  47
  48    Here “program” refers to any executable, not only the backend process.
  49
  50    Being slow or resource-hogging is not necessarily a bug. Read the
  51    documentation or ask on one of the mailing lists for help in tuning
  52    your applications. Failing to comply to the SQL standard is not
  53    necessarily a bug either, unless compliance for the specific feature is
  54    explicitly claimed.
  55
  56    Before you continue, check on the TODO list and in the FAQ to see if
  57    your bug is already known. If you cannot decode the information on the
  58    TODO list, report your problem. The least we can do is make the TODO
  59    list clearer.
  60
  61 5.2. What to Report #
  62
  63    The most important thing to remember about bug reporting is to state
  64    all the facts and only facts. Do not speculate what you think went
  65    wrong, what “it seemed to do”, or which part of the program has a
  66    fault. If you are not familiar with the implementation you would
  67    probably guess wrong and not help us a bit. And even if you are,
  68    educated explanations are a great supplement to but no substitute for
  69    facts. If we are going to fix the bug we still have to see it happen
  70    for ourselves first. Reporting the bare facts is relatively
  71    straightforward (you can probably copy and paste them from the screen)
  72    but all too often important details are left out because someone
  73    thought it does not matter or the report would be understood anyway.
  74
  75    The following items should be contained in every bug report:
  76      * The exact sequence of steps from program start-up necessary to
  77        reproduce the problem. This should be self-contained; it is not
  78        enough to send in a bare SELECT statement without the preceding
  79        CREATE TABLE and INSERT statements, if the output should depend on
  80        the data in the tables. We do not have the time to reverse-engineer
  81        your database schema, and if we are supposed to make up our own
  82        data we would probably miss the problem.
  83        The best format for a test case for SQL-related problems is a file
  84        that can be run through the psql frontend that shows the problem.
  85        (Be sure to not have anything in your ~/.psqlrc start-up file.) An
  86        easy way to create this file is to use pg_dump to dump out the
  87        table declarations and data needed to set the scene, then add the
  88        problem query. You are encouraged to minimize the size of your
  89        example, but this is not absolutely necessary. If the bug is
  90        reproducible, we will find it either way.
  91        If your application uses some other client interface, such as PHP,
  92        then please try to isolate the offending queries. We will probably
  93        not set up a web server to reproduce your problem. In any case
  94        remember to provide the exact input files; do not guess that the
  95        problem happens for “large files” or “midsize databases”, etc.
  96        since this information is too inexact to be of use.
  97      * The output you got. Please do not say that it “didn't work” or
  98        “crashed”. If there is an error message, show it, even if you do
  99        not understand it. If the program terminates with an operating
 100        system error, say which. If nothing at all happens, say so. Even if
 101        the result of your test case is a program crash or otherwise
 102        obvious it might not happen on our platform. The easiest thing is
 103        to copy the output from the terminal, if possible.
 104
 105 Note
 106        If you are reporting an error message, please obtain the most
 107        verbose form of the message. In psql, say \set VERBOSITY verbose
 108        beforehand. If you are extracting the message from the server log,
 109        set the run-time parameter log_error_verbosity to verbose so that
 110        all details are logged.
 111
 112 Note
 113        In case of fatal errors, the error message reported by the client
 114        might not contain all the information available. Please also look
 115        at the log output of the database server. If you do not keep your
 116        server's log output, this would be a good time to start doing so.
 117      * The output you expected is very important to state. If you just
 118        write “This command gives me that output.” or “This is not what I
 119        expected.”, we might run it ourselves, scan the output, and think
 120        it looks OK and is exactly what we expected. We should not have to
 121        spend the time to decode the exact semantics behind your commands.
 122        Especially refrain from merely saying that “This is not what SQL
 123        says/Oracle does.” Digging out the correct behavior from SQL is not
 124        a fun undertaking, nor do we all know how all the other relational
 125        databases out there behave. (If your problem is a program crash,
 126        you can obviously omit this item.)
 127      * Any command line options and other start-up options, including any
 128        relevant environment variables or configuration files that you
 129        changed from the default. Again, please provide exact information.
 130        If you are using a prepackaged distribution that starts the
 131        database server at boot time, you should try to find out how that
 132        is done.
 133      * Anything you did at all differently from the installation
 134        instructions.
 135      * The PostgreSQL version. You can run the command SELECT version();
 136        to find out the version of the server you are connected to. Most
 137        executable programs also support a --version option; at least
 138        postgres --version and psql --version should work. If the function
 139        or the options do not exist then your version is more than old
 140        enough to warrant an upgrade. If you run a prepackaged version,
 141        such as RPMs, say so, including any subversion the package might
 142        have. If you are talking about a Git snapshot, mention that,
 143        including the commit hash.
 144        If your version is older than 18.0 we will almost certainly tell
 145        you to upgrade. There are many bug fixes and improvements in each
 146        new release, so it is quite possible that a bug you have
 147        encountered in an older release of PostgreSQL has already been
 148        fixed. We can only provide limited support for sites using older
 149        releases of PostgreSQL; if you require more than we can provide,
 150        consider acquiring a commercial support contract.
 151      * Platform information. This includes the kernel name and version, C
 152        library, processor, memory information, and so on. In most cases it
 153        is sufficient to report the vendor and version, but do not assume
 154        everyone knows what exactly “Debian” contains or that everyone runs
 155        on x86_64. If you have installation problems then information about
 156        the toolchain on your machine (compiler, make, and so on) is also
 157        necessary.
 158
 159    Do not be afraid if your bug report becomes rather lengthy. That is a
 160    fact of life. It is better to report everything the first time than us
 161    having to squeeze the facts out of you. On the other hand, if your
 162    input files are huge, it is fair to ask first whether somebody is
 163    interested in looking into it. Here is an article that outlines some
 164    more tips on reporting bugs.
 165
 166    Do not spend all your time to figure out which changes in the input
 167    make the problem go away. This will probably not help solving it. If it
 168    turns out that the bug cannot be fixed right away, you will still have
 169    time to find and share your work-around. Also, once again, do not waste
 170    your time guessing why the bug exists. We will find that out soon
 171    enough.
 172
 173    When writing a bug report, please avoid confusing terminology. The
 174    software package in total is called “PostgreSQL”, sometimes “Postgres”
 175    for short. If you are specifically talking about the backend process,
 176    mention that, do not just say “PostgreSQL crashes”. A crash of a single
 177    backend process is quite different from crash of the parent “postgres”
 178    process; please don't say “the server crashed” when you mean a single
 179    backend process went down, nor vice versa. Also, client programs such
 180    as the interactive frontend “psql” are completely separate from the
 181    backend. Please try to be specific about whether the problem is on the
 182    client or server side.
 183
 184 5.3. Where to Report Bugs #
 185
 186    In general, send bug reports to the bug report mailing list at
 187    <pgsql-bugs@lists.postgresql.org>. You are requested to use a
 188    descriptive subject for your email message, perhaps parts of the error
 189    message.
 190
 191    Another method is to fill in the bug report web-form available at the
 192    project's web site. Entering a bug report this way causes it to be
 193    mailed to the <pgsql-bugs@lists.postgresql.org> mailing list.
 194
 195    If your bug report has security implications and you'd prefer that it
 196    not become immediately visible in public archives, don't send it to
 197    pgsql-bugs. Security issues can be reported privately to
 198    <security@postgresql.org>.
 199
 200    Do not send bug reports to any of the user mailing lists, such as
 201    <pgsql-sql@lists.postgresql.org> or
 202    <pgsql-general@lists.postgresql.org>. These mailing lists are for
 203    answering user questions, and their subscribers normally do not wish to
 204    receive bug reports. More importantly, they are unlikely to fix them.
 205
 206    Also, please do not send reports to the developers' mailing list
 207    <pgsql-hackers@lists.postgresql.org>. This list is for discussing the
 208    development of PostgreSQL, and it would be nice if we could keep the
 209    bug reports separate. We might choose to take up a discussion about
 210    your bug report on pgsql-hackers, if the problem needs more review.
 211
 212    If you have a problem with the documentation, the best place to report
 213    it is the documentation mailing list <pgsql-docs@lists.postgresql.org>.
 214    Please be specific about what part of the documentation you are unhappy
 215    with.
 216
 217    If your bug is a portability problem on a non-supported platform, send
 218    mail to <pgsql-hackers@lists.postgresql.org>, so we (and you) can work
 219    on porting PostgreSQL to your platform.
 220
 221 Note
 222
 223    Due to the unfortunate amount of spam going around, all of the above
 224    lists will be moderated unless you are subscribed. That means there
 225    will be some delay before the email is delivered. If you wish to
 226    subscribe to the lists, please visit https://lists.postgresql.org/ for
 227    instructions.