1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5. Bug Reporting Guidelines</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="resources.html" title="4. Further Information" /><link rel="next" href="tutorial.html" title="Part I. Tutorial" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5. Bug Reporting Guidelines</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="BUG-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5. Bug Reporting Guidelines</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.5">5.1. Identifying Bugs</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.6">5.2. What to Report</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.7">5.3. Where to Report Bugs</a></span></dt></dl></div><p>
When you find a bug in <span class="productname">PostgreSQL</span> we want to
hear about it. Your bug reports play an important part in making
<span class="productname">PostgreSQL</span> more reliable because even the utmost
care cannot guarantee that every part of
<span class="productname">PostgreSQL</span>
will work on every platform under every circumstance.
</p><p>
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.
</p><p>
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.
</p><div class="sect2" id="id-1.3.8.5"><div class="titlepage"><div><div><h3 class="title">5.1. Identifying Bugs</h3></div></div></div><p>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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 <span class="quote">“<span class="quote">disk full</span>”</span> message,
since you have to fix that yourself.)
</p></li><li class="listitem"><p>
A program produces the wrong output for any given input.
</p></li><li class="listitem"><p>
A program refuses to accept valid input (as defined in the documentation).
</p></li><li class="listitem"><p>
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.
</p></li><li class="listitem"><p>
<span class="productname">PostgreSQL</span> fails to compile, build, or
install according to the instructions on supported platforms.
</p></li></ul></div><p>
Here <span class="quote">“<span class="quote">program</span>”</span> refers to any executable, not only the backend process.
</p><p>
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 <acronym class="acronym">SQL</acronym> standard is
not necessarily a bug either, unless compliance for the
specific feature is explicitly claimed.
</p><p>
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.
</p></div><div class="sect2" id="id-1.3.8.6"><div class="titlepage"><div><div><h3 class="title">5.2. What to Report</h3></div></div></div><p>
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
<span class="quote">“<span class="quote">it seemed to do</span>”</span>, 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.
</p><p>
The following items should be contained in every bug report:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The exact sequence of steps <span class="emphasis"><em>from program
start-up</em></span> necessary to reproduce the problem. This
should be self-contained; it is not enough to send in a bare
<code class="command">SELECT</code> statement without the preceding
<code class="command">CREATE TABLE</code> and <code class="command">INSERT</code>
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.
</p><p>
The best format for a test case for SQL-related problems is a
file that can be run through the <span class="application">psql</span>
frontend that shows the problem. (Be sure to not have anything
in your <code class="filename">~/.psqlrc</code> start-up file.) An easy
way to create this file is to use <span class="application">pg_dump</span>
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.
</p><p>
If your application uses some other client interface, such as <span class="application">PHP</span>, 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
<span class="quote">“<span class="quote">large files</span>”</span> or <span class="quote">“<span class="quote">midsize databases</span>”</span>, etc. since this
information is too inexact to be of use.
</p></li><li class="listitem"><p>
The output you got. Please do not say that it <span class="quote">“<span class="quote">didn't work</span>”</span> or
<span class="quote">“<span class="quote">crashed</span>”</span>. 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.
</p><div class="note"><h3 class="title">Note</h3><p>
If you are reporting an error message, please obtain the most verbose
form of the message. In <span class="application">psql</span>, say <code class="literal">\set
VERBOSITY verbose</code> beforehand. If you are extracting the message
from the server log, set the run-time parameter
<a class="xref" href="runtime-config-logging.html#GUC-LOG-ERROR-VERBOSITY">log_error_verbosity</a> to <code class="literal">verbose</code> so that all
details are logged.
</p></div><div class="note"><h3 class="title">Note</h3><p>
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.
</p></div></li><li class="listitem"><p>
The output you expected is very important to state. If you just write
<span class="quote">“<span class="quote">This command gives me that output.</span>”</span> or <span class="quote">“<span class="quote">This is not
what I expected.</span>”</span>, 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 <span class="quote">“<span class="quote">This is not what SQL says/Oracle
does.</span>”</span> Digging out the correct behavior from <acronym class="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.)
</p></li><li class="listitem"><p>
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.
</p></li><li class="listitem"><p>
Anything you did at all differently from the installation
instructions.
</p></li><li class="listitem"><p>
The <span class="productname">PostgreSQL</span> version. You can run the command
<code class="literal">SELECT version();</code> to
find out the version of the server you are connected to. Most executable
programs also support a <code class="option">--version</code> option; at least
<code class="literal">postgres --version</code> and <code class="literal">psql --version</code>
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.
</p><p>
If your version is older than 13.4 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 <span class="productname">PostgreSQL</span>
has already been fixed. We can only provide limited support for
sites using older releases of <span class="productname">PostgreSQL</span>; if you
require more than we can provide, consider acquiring a
commercial support contract.
</p><p>
</p></li><li class="listitem"><p>
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 <span class="quote">“<span class="quote">Debian</span>”</span>
contains or that everyone runs on x86_64. If you have
installation problems then information about the toolchain on
your machine (compiler, <span class="application">make</span>, and so
on) is also necessary.
</p></li></ul></div><p>
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 <a class="ulink" href="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target="_top">article</a>
that outlines some more tips on reporting bugs.
</p><p>
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.
</p><p>
When writing a bug report, please avoid confusing terminology.
The software package in total is called <span class="quote">“<span class="quote">PostgreSQL</span>”</span>,
sometimes <span class="quote">“<span class="quote">Postgres</span>”</span> for short. If you
are specifically talking about the backend process, mention that, do not
just say <span class="quote">“<span class="quote">PostgreSQL crashes</span>”</span>. A crash of a single
backend process is quite different from crash of the parent
<span class="quote">“<span class="quote">postgres</span>”</span> process; please don't say <span class="quote">“<span class="quote">the server
crashed</span>”</span> when you mean a single backend process went down, nor vice versa.
Also, client programs such as the interactive frontend <span class="quote">“<span class="quote"><span class="application">psql</span></span>”</span>
are completely separate from the backend. Please try to be specific
about whether the problem is on the client or server side.
</p></div><div class="sect2" id="id-1.3.8.7"><div class="titlepage"><div><div><h3 class="title">5.3. Where to Report Bugs</h3></div></div></div><p>
In general, send bug reports to the bug report mailing list at
<code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code>.
You are requested to use a descriptive subject for your email
message, perhaps parts of the error message.
</p><p>
Another method is to fill in the bug report web-form available
at the project's
<a class="ulink" href="https://www.postgresql.org/" target="_top">web site</a>.
Entering a bug report this way causes it to be mailed to the
<code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code> mailing list.
</p><p>
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
<code class="literal">pgsql-bugs</code>. Security issues can be
reported privately to <code class="email"><<a class="email" href="mailto:security@postgresql.org">security@postgresql.org</a>></code>.
</p><p>
Do not send bug reports to any of the user mailing lists, such as
<code class="email"><<a class="email" href="mailto:pgsql-sql@lists.postgresql.org">pgsql-sql@lists.postgresql.org</a>></code> or
<code class="email"><<a class="email" href="mailto:pgsql-general@lists.postgresql.org">pgsql-general@lists.postgresql.org</a>></code>.
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.
</p><p>
Also, please do <span class="emphasis"><em>not</em></span> send reports to
the developers' mailing list <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>.
This list is for discussing the
development of <span class="productname">PostgreSQL</span>, 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 <code class="literal">pgsql-hackers</code>,
if the problem needs more review.
</p><p>
If you have a problem with the documentation, the best place to report it
is the documentation mailing list <code class="email"><<a class="email" href="mailto:pgsql-docs@lists.postgresql.org">pgsql-docs@lists.postgresql.org</a>></code>.
Please be specific about what part of the documentation you are unhappy
with.
</p><p>
If your bug is a portability problem on a non-supported platform,
send mail to <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>,
so we (and you) can work on
porting <span class="productname">PostgreSQL</span> to your platform.
</p><div class="note"><h3 class="title">Note</h3><p>
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
<a class="ulink" href="https://lists.postgresql.org/" target="_top">https://lists.postgresql.org/</a> for instructions.
</p></div></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Further Information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part I. Tutorial</td></tr></table></div></body></html>
|
