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