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