4
<title>PostgreSQL Coding Conventions</title>
6
<sect1 id="source-format">
7
<title>Formatting</title>
10
Source code formatting uses 4 column tab spacing, with
11
tabs preserved (i.e., tabs are not expanded to spaces).
12
Each logical indentation level is one additional tab stop.
16
Layout rules (brace positioning, etc) follow BSD conventions. In
17
particular, curly braces for the controlled blocks of <literal>if</>,
18
<literal>while</>, <literal>switch</>, etc go on their own lines.
22
Do not use C++ style comments (<literal>//</> comments). Strict ANSI C
23
compilers do not accept them. For the same reason, do not use C++
24
extensions such as declaring new variables mid-block.
28
The preferred style for multi-line comment blocks is
31
* comment text begins here
35
Note that comment blocks that begin in column 1 will be preserved as-is
36
by <application>pgindent</>, but it will re-flow indented comment blocks
37
as though they were plain text. If you want to preserve the line breaks
38
in an indented block, add dashes like this:
41
* comment text begins here
49
While submitted patches do not absolutely have to follow these formatting
50
rules, it's a good idea to do so. Your code will get run through
51
<application>pgindent</> before the next release, so there's no point in
52
making it look nice under some other set of formatting conventions.
56
The <filename>src/tools</filename> directory contains sample settings
57
files that can be used with the <productname>emacs</productname>,
58
<productname>xemacs</productname> or <productname>vim</productname>
59
editors to help ensure that they format code according to these
64
The text browsing tools <application>more</application> and
65
<application>less</application> can be invoked as:
70
to make them show tabs appropriately.
74
<sect1 id="error-message-reporting">
75
<title>Reporting Errors Within the Server</title>
78
<primary>ereport</primary>
81
<primary>elog</primary>
85
Error, warning, and log messages generated within the server code
86
should be created using <function>ereport</>, or its older cousin
87
<function>elog</>. The use of this function is complex enough to
88
require some explanation.
92
There are two required elements for every message: a severity level
93
(ranging from <literal>DEBUG</> to <literal>PANIC</>) and a primary
94
message text. In addition there are optional elements, the most
95
common of which is an error identifier code that follows the SQL spec's
97
<function>ereport</> itself is just a shell function, that exists
98
mainly for the syntactic convenience of making message generation
99
look like a function call in the C source code. The only parameter
100
accepted directly by <function>ereport</> is the severity level.
101
The primary message text and any optional message elements are
102
generated by calling auxiliary functions, such as <function>errmsg</>,
103
within the <function>ereport</> call.
107
A typical call to <function>ereport</> might look like this:
110
(errcode(ERRCODE_DIVISION_BY_ZERO),
111
errmsg("division by zero")));
113
This specifies error severity level <literal>ERROR</> (a run-of-the-mill
114
error). The <function>errcode</> call specifies the SQLSTATE error code
115
using a macro defined in <filename>src/include/utils/errcodes.h</>. The
116
<function>errmsg</> call provides the primary message text. Notice the
117
extra set of parentheses surrounding the auxiliary function calls —
118
these are annoying but syntactically necessary.
122
Here is a more complex example:
125
(errcode(ERRCODE_AMBIGUOUS_FUNCTION),
126
errmsg("function %s is not unique",
127
func_signature_string(funcname, nargs,
129
errhint("Unable to choose a best candidate function. "
130
"You might need to add explicit typecasts.")));
132
This illustrates the use of format codes to embed run-time values into
133
a message text. Also, an optional <quote>hint</> message is provided.
137
The available auxiliary routines for <function>ereport</> are:
141
<function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
142
code for the condition. If this routine is not called, the error
143
identifier defaults to
144
<literal>ERRCODE_INTERNAL_ERROR</> when the error severity level is
145
<literal>ERROR</> or higher, <literal>ERRCODE_WARNING</> when the
146
error level is <literal>WARNING</>, otherwise (for <literal>NOTICE</>
147
and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</>.
148
While these defaults are often convenient, always think whether they
149
are appropriate before omitting the <function>errcode()</> call.
154
<function>errmsg(const char *msg, ...)</function> specifies the primary error
155
message text, and possibly run-time values to insert into it. Insertions
156
are specified by <function>sprintf</>-style format codes. In addition to
157
the standard format codes accepted by <function>sprintf</>, the format
158
code <literal>%m</> can be used to insert the error message returned
159
by <function>strerror</> for the current value of <literal>errno</>.
162
That is, the value that was current when the <function>ereport</> call
163
was reached; changes of <literal>errno</> within the auxiliary reporting
164
routines will not affect it. That would not be true if you were to
165
write <literal>strerror(errno)</> explicitly in <function>errmsg</>'s
166
parameter list; accordingly, do not do so.
169
<literal>%m</> does not require any
170
corresponding entry in the parameter list for <function>errmsg</>.
171
Note that the message string will be run through <function>gettext</>
172
for possible localization before format codes are processed.
177
<function>errmsg_internal(const char *msg, ...)</function> is the same as
178
<function>errmsg</>, except that the message string will not be
179
translated nor included in the internationalization message dictionary.
180
This should be used for <quote>cannot happen</> cases that are probably
181
not worth expending translation effort on.
186
<function>errdetail(const char *msg, ...)</function> supplies an optional
187
<quote>detail</> message; this is to be used when there is additional
188
information that seems inappropriate to put in the primary message.
189
The message string is processed in just the same way as for
195
<function>errdetail_log(const char *msg, ...)</function> is the same as
196
<function>errdetail</> except that this string goes only to the server
197
log, never to the client. If both <function>errdetail</> and
198
<function>errdetail_log</> are used then one string goes to the client
199
and the other to the log. This is useful for error details that are
200
too security-sensitive or too bulky to include in the report
206
<function>errhint(const char *msg, ...)</function> supplies an optional
207
<quote>hint</> message; this is to be used when offering suggestions
208
about how to fix the problem, as opposed to factual details about
210
The message string is processed in just the same way as for
216
<function>errcontext(const char *msg, ...)</function> is not normally called
217
directly from an <function>ereport</> message site; rather it is used
218
in <literal>error_context_stack</> callback functions to provide
219
information about the context in which an error occurred, such as the
220
current location in a PL function.
221
The message string is processed in just the same way as for
222
<function>errmsg</>. Unlike the other auxiliary functions, this can
223
be called more than once per <function>ereport</> call; the successive
224
strings thus supplied are concatenated with separating newlines.
229
<function>errposition(int cursorpos)</function> specifies the textual location
230
of an error within a query string. Currently it is only useful for
231
errors detected in the lexical and syntactic analysis phases of
237
<function>errcode_for_file_access()</> is a convenience function that
238
selects an appropriate SQLSTATE error identifier for a failure in a
239
file-access-related system call. It uses the saved
240
<literal>errno</> to determine which error code to generate.
241
Usually this should be used in combination with <literal>%m</> in the
242
primary error message text.
247
<function>errcode_for_socket_access()</> is a convenience function that
248
selects an appropriate SQLSTATE error identifier for a failure in a
249
socket-related system call.
254
<function>errhidestmt(bool hide_stmt)</function> can be called to specify
255
suppression of the <literal>STATEMENT:</> portion of a message in the
256
postmaster log. Generally this is appropriate if the message text
257
includes the current statement already.
264
There is an older function <function>elog</> that is still heavily used.
265
An <function>elog</> call:
267
elog(level, "format string", ...);
269
is exactly equivalent to:
271
ereport(level, (errmsg_internal("format string", ...)));
273
Notice that the SQLSTATE error code is always defaulted, and the message
274
string is not subject to translation.
275
Therefore, <function>elog</> should be used only for internal errors and
276
low-level debug logging. Any message that is likely to be of interest to
277
ordinary users should go through <function>ereport</>. Nonetheless,
278
there are enough internal <quote>cannot happen</> error checks in the
279
system that <function>elog</> is still widely used; it is preferred for
280
those messages for its notational simplicity.
284
Advice about writing good error messages can be found in
285
<xref linkend="error-style-guide">.
289
<sect1 id="error-style-guide">
290
<title>Error Message Style Guide</title>
293
This style guide is offered in the hope of maintaining a consistent,
294
user-friendly style throughout all the messages generated by
295
<productname>PostgreSQL</>.
299
<title>What goes where</title>
302
The primary message should be short, factual, and avoid reference to
303
implementation details such as specific function names.
304
<quote>Short</quote> means <quote>should fit on one line under normal
305
conditions</quote>. Use a detail message if needed to keep the primary
306
message short, or if you feel a need to mention implementation details
307
such as the particular system call that failed. Both primary and detail
308
messages should be factual. Use a hint message for suggestions about what
309
to do to fix the problem, especially if the suggestion might not always be
314
For example, instead of:
316
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
317
(plus a long addendum that is basically a hint)
321
Primary: could not create shared memory segment: %m
322
Detail: Failed syscall was shmget(key=%d, size=%u, 0%o).
328
Rationale: keeping the primary message short helps keep it to the point,
329
and lets clients lay out screen space on the assumption that one line is
330
enough for error messages. Detail and hint messages can be relegated to a
331
verbose mode, or perhaps a pop-up error-details window. Also, details and
332
hints would normally be suppressed from the server log to save
333
space. Reference to implementation details is best avoided since users
334
don't know the details anyway.
340
<title>Formatting</title>
343
Don't put any specific assumptions about formatting into the message
344
texts. Expect clients and the server log to wrap lines to fit their own
345
needs. In long messages, newline characters (\n) can be used to indicate
346
suggested paragraph breaks. Don't end a message with a newline. Don't
347
use tabs or other formatting characters. (In error context displays,
348
newlines are automatically added to separate levels of context such as
353
Rationale: Messages are not necessarily displayed on terminal-type
354
displays. In GUI displays or browsers these formatting instructions are
361
<title>Quotation marks</title>
364
English text should use double quotes when quoting is appropriate.
365
Text in other languages should consistently use one kind of quotes that is
366
consistent with publishing customs and computer output of other programs.
370
Rationale: The choice of double quotes over single quotes is somewhat
371
arbitrary, but tends to be the preferred use. Some have suggested
372
choosing the kind of quotes depending on the type of object according to
373
SQL conventions (namely, strings single quoted, identifiers double
374
quoted). But this is a language-internal technical issue that many users
375
aren't even familiar with, it won't scale to other kinds of quoted terms,
376
it doesn't translate to other languages, and it's pretty pointless, too.
382
<title>Use of quotes</title>
385
Use quotes always to delimit file names, user-supplied identifiers, and
386
other variables that might contain words. Do not use them to mark up
387
variables that will not contain words (for example, operator names).
391
There are functions in the backend that will double-quote their own output
392
at need (for example, <function>format_type_be</>()). Do not put
393
additional quotes around the output of such functions.
397
Rationale: Objects can have names that create ambiguity when embedded in a
398
message. Be consistent about denoting where a plugged-in name starts and
399
ends. But don't clutter messages with unnecessary or duplicate quote
406
<title>Grammar and punctuation</title>
409
The rules are different for primary error messages and for detail/hint
414
Primary error messages: Do not capitalize the first letter. Do not end a
415
message with a period. Do not even think about ending a message with an
420
Detail and hint messages: Use complete sentences, and end each with
421
a period. Capitalize the first word of sentences. Put two spaces after
422
the period if another sentence follows (for English text; might be
423
inappropriate in other languages).
427
Rationale: Avoiding punctuation makes it easier for client applications to
428
embed the message into a variety of grammatical contexts. Often, primary
429
messages are not grammatically complete sentences anyway. (And if they're
430
long enough to be more than one sentence, they should be split into
431
primary and detail parts.) However, detail and hint messages are longer
432
and might need to include multiple sentences. For consistency, they should
433
follow complete-sentence style even when there's only one sentence.
439
<title>Upper case vs. lower case</title>
442
Use lower case for message wording, including the first letter of a
443
primary error message. Use upper case for SQL commands and key words if
444
they appear in the message.
448
Rationale: It's easier to make everything look more consistent this
449
way, since some messages are complete sentences and some not.
455
<title>Avoid passive voice</title>
458
Use the active voice. Use complete sentences when there is an acting
459
subject (<quote>A could not do B</quote>). Use telegram style without
460
subject if the subject would be the program itself; do not use
461
<quote>I</quote> for the program.
465
Rationale: The program is not human. Don't pretend otherwise.
471
<title>Present vs past tense</title>
474
Use past tense if an attempt to do something failed, but could perhaps
475
succeed next time (perhaps after fixing some problem). Use present tense
476
if the failure is certainly permanent.
480
There is a nontrivial semantic difference between sentences of the form:
482
could not open file "%s": %m
486
cannot open file "%s"
488
The first one means that the attempt to open the file failed. The
489
message should give a reason, such as <quote>disk full</quote> or
490
<quote>file doesn't exist</quote>. The past tense is appropriate because
491
next time the disk might not be full anymore or the file in question might
496
The second form indicates that the functionality of opening the named file
497
does not exist at all in the program, or that it's conceptually
498
impossible. The present tense is appropriate because the condition will
499
persist indefinitely.
503
Rationale: Granted, the average user will not be able to draw great
504
conclusions merely from the tense of the message, but since the language
505
provides us with a grammar we should use it correctly.
511
<title>Type of the object</title>
514
When citing the name of an object, state what kind of object it is.
518
Rationale: Otherwise no one will know what <quote>foo.bar.baz</>
525
<title>Brackets</title>
528
Square brackets are only to be used (1) in command synopses to denote
529
optional arguments, or (2) to denote an array subscript.
533
Rationale: Anything else does not correspond to widely-known customary
534
usage and will confuse people.
540
<title>Assembling error messages</title>
543
When a message includes text that is generated elsewhere, embed it in
546
could not open file %s: %m
551
Rationale: It would be difficult to account for all possible error codes
552
to paste this into a single smooth sentence, so some sort of punctuation
553
is needed. Putting the embedded text in parentheses has also been
554
suggested, but it's unnatural if the embedded text is likely to be the
555
most important part of the message, as is often the case.
561
<title>Reasons for errors</title>
564
Messages should always state the reason why an error occurred.
567
BAD: could not open file %s
568
BETTER: could not open file %s (I/O failure)
570
If no reason is known you better fix the code.
576
<title>Function names</title>
579
Don't include the name of the reporting routine in the error text. We have
580
other mechanisms for finding that out when needed, and for most users it's
581
not helpful information. If the error text doesn't make as much sense
582
without the function name, reword it.
584
BAD: pg_atoi: error in "z": cannot parse "z"
585
BETTER: invalid input syntax for integer: "z"
590
Avoid mentioning called function names, either; instead say what the code
593
BAD: open() failed: %m
594
BETTER: could not open file %s: %m
596
If it really seems necessary, mention the system call in the detail
597
message. (In some cases, providing the actual values passed to the
598
system call might be appropriate information for the detail message.)
602
Rationale: Users don't know what all those functions do.
608
<title>Tricky words to avoid</title>
611
<title>Unable</title>
613
<quote>Unable</quote> is nearly the passive voice. Better use
614
<quote>cannot</quote> or <quote>could not</quote>, as appropriate.
621
Error messages like <quote>bad result</quote> are really hard to interpret
622
intelligently. It's better to write why the result is <quote>bad</quote>,
623
e.g., <quote>invalid format</quote>.
628
<title>Illegal</title>
630
<quote>Illegal</quote> stands for a violation of the law, the rest is
631
<quote>invalid</quote>. Better yet, say why it's invalid.
636
<title>Unknown</title>
638
Try to avoid <quote>unknown</quote>. Consider <quote>error: unknown
639
response</quote>. If you don't know what the response is, how do you know
640
it's erroneous? <quote>Unrecognized</quote> is often a better choice.
641
Also, be sure to include the value being complained of.
643
BAD: unknown node type
644
BETTER: unrecognized node type: 42
650
<title>Find vs. Exists</title>
652
If the program uses a nontrivial algorithm to locate a resource (e.g., a
653
path search) and that algorithm fails, it is fair to say that the program
654
couldn't <quote>find</quote> the resource. If, on the other hand, the
655
expected location of the resource is known but the program cannot access
656
it there then say that the resource doesn't <quote>exist</quote>. Using
657
<quote>find</quote> in this case sounds weak and confuses the issue.
662
<title>May vs. Can vs. Might</title>
664
<quote>May</quote> suggests permission (e.g. "You may borrow my rake."),
665
and has little use in documentation or error messages.
666
<quote>Can</quote> suggests ability (e.g. "I can lift that log."),
667
and <quote>might</quote> suggests possibility (e.g. "It might rain
668
today."). Using the proper word clarifies meaning and assists
674
<title>Contractions</title>
676
Avoid contractions, like <quote>can't</quote>; use
677
<quote>cannot</quote> instead.
684
<title>Proper spelling</title>
687
Spell out words in full. For instance, avoid:
718
Rationale: This will improve consistency.
724
<title>Localization</title>
727
Keep in mind that error message texts need to be translated into other
728
languages. Follow the guidelines in <xref linkend="nls-guidelines">
729
to avoid making life difficult for translators.
added
removed
doc/src/sgml/sources.sgml
