2 <title>Problem Reporting Guidelines</title>
5 When you encounter a problem in <productname>PostgreSQL</productname> we want to
6 hear about it. Your bug reports are an important part in making
7 <productname>PostgreSQL</productname> more reliable because even the utmost
8 care cannot guarantee that every part of PostgreSQL will work on every
9 platform under every circumstance.
13 The following suggestions are intended to assist you in forming bug reports
14 that can be handled in an effective fashion. No one is required to follow
15 them but it tends to be to everyone's advantage.
19 We cannot promise to fix every bug right away. If the bug is obvious, critical,
20 or affects a lot of users, chances are good that someone will look into it. It
21 could also happen that we tell you to update to a newer version to see if the
22 bug happens there. Or we might decide that the bug
23 cannot be fixed before some major rewrite we might be planning is done. Or
24 perhaps it's simply too hard and there are more important things on the agenda.
25 If you need help immediately, consider obtaining a commercial support contract.
29 <title>Identifying Bugs</title>
32 Before you ask "Is this a bug?", please read and re-read the
33 documentation to verify that you can really do whatever it is you are
34 trying. If it is not clear from the documentation whether you can do
35 something or not, please report that too; it's a bug in the documentation.
36 If it turns out that the program does something different from what the
37 documentation says, that's a bug. That might include, but is not limited to,
38 the following circumstances:
43 A program terminates with a fatal signal or an operating system
44 error message that would point to a problem in the program (a
45 counterexample might be a "disk full" message,
46 since that must be fixed outside of <productname>Postgres</productname>).
52 A program produces the wrong output for any given input.
58 A program refuses to accept valid input.
64 A program accepts invalid input without a notice or error message.
70 <productname>PostgreSQL</productname> fails to compile, build, or
71 install according to the instructions on supported platforms.
76 Here "<literal>program</literal>" refers to any executable, not only the backend server.
80 Being slow or resource-hogging is not necessarily a bug. Read the documentation
81 or ask on one of the mailing lists for help in tuning your applications. Failing
82 to comply to <acronym>SQL</acronym> is not a bug unless compliance for the
83 specific feature is explicitly claimed.
87 Before you continue, check on the TODO list and in the FAQ to see if your bug is
88 already known. If you can't decode the information on the TODO list, report your
89 problem. The least we can do is make the TODO list clearer.
94 <title>What to report</title>
97 The most important thing to remember about bug reporting is to state all
98 the facts and only facts. Do not speculate what you think went wrong, what
99 "it seemed to do", or which part of the program has a fault.
100 If you are not familiar with the implementation you would probably guess
101 wrong and not help us a bit. And even if you are, educated explanations are
102 a great supplement to but no substitute for facts. If we are going to fix
103 the bug we still have to see it happen for ourselves first.
104 Reporting the bare facts
105 is relatively straightforward (you can probably copy and paste them from the
106 screen) but all too often important details are left out because someone
107 thought it doesn't matter or the report would be understood
112 The following items should be contained in every bug report:
117 The exact sequence of steps <emphasis>from program start-up</emphasis>
118 necessary to reproduce the problem. This should be self-contained;
119 it is not enough to send in a bare select statement without the
120 preceeding create table and insert statements, if the output should
121 depend on the data in the tables. We do not have the time
122 to decode your database schema, and if we are supposed to make up
123 our own data we would probably miss the problem.
124 The best format for a test case for
125 query-language related problems is a file that can be run through the
126 <application>psql</application> frontend
127 that shows the problem. (Be sure to not have anything in your
128 <filename>~/.psqlrc</filename> start-up file.) You are encouraged to
129 minimize the size of your example, but this is not absolutely necessary.
130 If the bug is reproduceable, we'll find it either way.
133 If your application uses some other client interface, such as PHP, then
134 please try to isolate the offending queries. We probably won't set up a
135 web server to reproduce your problem. In any case remember to provide
136 the exact input files, do not guess that the problem happens for
137 "large files" or "mid-size databases", etc. since this
138 information is too inexact to be of use.
144 The output you got. Please do not say that it "didn't work" or
145 "failed". If there is an error message,
146 show it, even if you don't understand it. If the program terminates with
147 an operating system error, say which. If nothing at all happens, say so.
148 Even if the result of your test case is a program crash or otherwise obvious
149 it might not happen on our platform. The easiest thing is to copy the output
150 from the terminal, if possible.
154 In case of fatal errors, the error message provided by the client might
155 not contain all the information available. In that case, also look at the
156 output of the database server. If you do not keep your server output,
157 this would be a good time to start doing so.
164 The output you expected is very important to state. If you just write
165 "This command gives me that output." or "This is not
166 what I expected.", we might run it ourselves, scan the output, and
167 think it looks okay and is exactly what we expected. We shouldn't have to
168 spend the time to decode the exact semantics behind your commands.
169 Especially refrain from merely saying that "This is not what SQL says/Oracle
170 does." Digging out the correct behavior from <acronym>SQL</acronym>
171 is not a fun undertaking, nor do we all know how all the other relational
172 databases out there behave. (If your problem is a program crash you can
173 obviously omit this item.)
179 Any command line options and other start-up options, including concerned
180 environment variables or configuration files that you changed from the
181 default. Again, be exact. If you are using a pre-packaged
182 distribution that starts the database server at boot time, you should try
183 to find out how that is done.
189 Anything you did at all differently from the installation instructions.
195 The <productname>PostgreSQL</productname> version. You can run the command
196 <literal>SELECT version();</literal> to
197 find out what version you are currently running.
198 If this function does not exist, say so, then we know that
199 your version is old enough. If you can't start up the server or a
200 client, look into the README file in the source directory or at the
201 name of your distribution file or package name. If your version is older
202 than 7.0 we will almost certainly tell you to upgrade. There are tons
203 of bug fixes in each new version, that's why we write them.
206 If you run a pre-packaged version, such as RPMs, say so, including any
207 subversion the package may have. If you are talking about a CVS
208 snapshot, mention that, including its date and time.
214 Platform information. This includes the kernel name and version, C library,
215 processor, memory information. In most cases it is sufficient to report
216 the vendor and version, but do not assume everyone knows what exactly
217 "Debian" contains or that everyone runs on Pentiums. If
218 you have installation problems information about compilers, make, etc.
224 Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
225 It's better to report everything the first time than us having to squeeze the
226 facts out of you. On the other hand, if your input files are huge, it is
227 fair to ask first whether somebody is interested in looking into it.
231 Do not spend all your time to figure out which changes in the input make
232 the problem go away. This will probably not help solving it. If it turns
233 out that the bug can't be fixed right away, you will still have time to
234 find and share your work around. Also, once again, do not waste your time
235 guessing why the bug exists. We'll find that out soon enough.
239 When writing a bug report, please choose non-confusing terminology.
240 The software package as such is called "PostgreSQL",
241 sometimes "Postgres" for short. (Sometimes
242 the abbreviation "Pgsql" is used but don't do that.) When you
243 are specifically talking about the backend server, mention that, don't
244 just say "Postgres crashes". The interactive frontend is called
245 "psql" and is for all intends and purposes completely separate
251 <title>Where to report bugs</title>
254 In general, send bug reports to
255 <ulink url="mailto:pgsql-bugs@postgresql.org">the bug report
256 mailing list</ulink>.
257 You are invited to find a descriptive subject for your email
258 message, perhaps parts of the error message.
262 Do not send bug reports to any of the user mailing lists, such as
264 <ulink url="mailto:pgsql-sql@postgresql.org">the SQL language
267 <ulink url="mailto:pgsql-general@postgresql.org">the general topics
268 mailing list</ulink>.
269 These mailing lists are for answering
270 user questions and their subscribers normally do not wish to receive
271 bug reports. More importantly, they are unlikely to fix them.
275 Also, please do <emphasis>not</emphasis> send reports to
276 <ulink url="mailto:pgsql-hackers@postgresql.org">the developers'
277 mailing list</ulink>.
278 This list is for discussing the
279 development of <productname>PostgreSQL</productname> and it would be nice
280 if we could keep the bug reports separate. We might choose to take up a
282 about your bug report on it, if the bug needs more review.
286 If you have a problem with the documentation, send email to
287 <ulink url="mailto:pgsql-docs@postgresql.org">the documentation
288 mailing list</ulink>.
289 Mention the document, chapter, and sections in your problem report.
293 If your bug is a portability problem on a non-supported platform,
295 <ulink url="mailto:pgsql-ports@postgresql.org">the porting issues mail list</ulink>,
296 so we (and you) can work on
297 porting <productname>PostgreSQL</productname> to your platform.
302 Due to the unfortunate amount of spam going around, all of the above
303 email addresses are closed mailing lists. That is, you need to be
304 subscribed to them in order to be allowed to post. If you simply
305 want to send mail but do not want to receive list traffic, you can
306 subscribe to the special pgsql-loophole mailing list, which
307 allows you to post to all <productname>PostgreSQL</productname>
308 mailing lists without receiving any messages. Send email to
309 <ulink url="mailto:pgsql-loophole-request@postgresql.org">pgsql-loophole-request@postgresql.org</ulink>
316 <!-- Keep this comment at the end of the file
321 sgml-minimize-attributes:nil
322 sgml-always-quote-attributes:t
325 sgml-parent-document:nil
326 sgml-default-dtd-file:"./reference.ced"
327 sgml-exposed-tags:nil
328 sgml-local-catalogs:("/usr/lib/sgml/catalog")
329 sgml-local-ecat-files:nil