138
Chapter 50. PostgreSQL Coding Conventions
•
errmsg_internal(const char
*
msg, ...)
is the same as
errmsg
,except that the message
string willnotbetranslated nor included inthe internationalizationmessage dictionary. This should
be used for “cannot happen” cases that are probably not worth expending translation effort on.
•
errmsg_plural(const char
*
fmt_singular, const char
*
fmt_plural, unsigned
long n, ...)
is like
errmsg
, but with support for various plural forms of the message.
fmt_singular
is the English singular format,
fmt_plural
is the English plural format,
n
is the
integer value that determines which plural form is needed, and the remaining arguments are
formatted according to the selected format string. For more information see Section 51.2.2.
•
errdetail(const char
*
msg, ...)
supplies an optional “detail” message; this is to be used
when there is additional information that seems inappropriate to put in the primary message. The
message string is processedin just the same way as for
errmsg
.
•
errdetail_internal(const char
*
msg, ...)
is the same as
errdetail
,except that the
message string will not be translated nor included in the internationalization message dictionary.
This should be used for detail messages that are not worth expending translation effort on, for
instance because they are too technical to be useful to most users.
•
errdetail_plural(const char
*
fmt_singular, const char
*
fmt_plural,
unsigned long n, ...)
is like
errdetail
,but with support for various plural forms of the
message. For more information see Section 51.2.2.
•
errdetail_log(const char
*
msg, ...)
is the same as
errdetail
except that this string
goes only tothe server log, never to the client. If both
errdetail
(or one of its equivalents above)
and
errdetail_log
are used then one string goes to the client and the other to the log. This is
useful for error details thatare too security-sensitive or toobulky toinclude in the report sentto the
client.
•
errdetail_log_plural(const char
*
fmt_singular, const char
*
fmt_plural,
unsigned long n, ...)
is like
errdetail_log
,but with support for various plural forms of
the message. For more information see Section 51.2.2.
•
errhint(const char
*
msg, ...)
supplies anoptional“hint”message; thisis tobeusedwhen
offering suggestions about how to fix the problem, as opposed to factual details about what went
wrong. The message string is processed in just the same way as for
errmsg
.
•
errcontext(const char
*
msg, ...)
is not normally called directly from an
ereport
mes-
sage site; rather it is used in
error_context_stack
callback functions to provide information
about the context in which an error occurred, such as the current location in a PL function. The
message string is processed in just the same way as for
errmsg
.Unlike the other auxiliary func-
tions, this can be called more than once per
ereport
call; the successive strings thus supplied are
concatenated with separating newlines.
•
errposition(int cursorpos)
specifies the textual location of an error within a query string.
Currently it is only useful for errors detected in the lexical and syntactic analysis phases of query
processing.
•
errtable(Relation rel)
specifiesa relationwhosename and schema nameshouldbeincluded
as auxiliary fields in the error report.
•
errtablecol(Relation rel, int attnum)
specifies a column whose name, table name, and
schema name should be included as auxiliary fields in the error report.
•
errtableconstraint(Relation rel, const char
*
conname)
specifies a table constraint
whose name, table name, and schema name should be included as auxiliary fields in the error
report. Indexes shouldbe considered to be constraints for this purpose, whether or not they have an
associated
pg_constraint
entry. Be careful to pass the underlying heap relation, not the index
itself, as
rel
.
1902
78
Chapter 50. PostgreSQL Coding Conventions
•
errdatatype(Oid datatypeOid)
specifies a data type whose name and schema name should
be included as auxiliary fields in the error report.
•
errdomainconstraint(Oid datatypeOid, const char
*
conname)
specifies a domain
constraint whose name, domain name, and schema name should be included as auxiliary fields in
the error report.
•
errcode_for_file_access()
is a convenience functionthatselects an appropriateSQLSTATE
error identifier for a failurein afile-access-related system call. It uses the saved
errno
todetermine
which error code to generate. Usually this should be used in combination with
%m
in the primary
error message text.
•
errcode_for_socket_access()
is a convenience function that selects an appropriate SQL-
STATE error identifier for a failure in a socket-relatedsystem call.
•
errhidestmt(bool hide_stmt)
can be called to specify suppression of the
STATEMENT:
por-
tion of a message in the postmaster log. Generally this is appropriate if the message text includes
the current statement already.
Note: At most one of the functions
errtable
,
errtablecol
,
errtableconstraint
,
errdatatype
,or
errdomainconstraint
should be used in an
ereport
call. These functions
exist to allow applications to extract the name of a database object associated with the error
condition without havingto examine the potentially-localized error message text. These functions
shouldbe used in error reports for which it’s likely that applications would wish to have automatic
error handling. As of PostgreSQL 9.3, complete coverage exists only for errors in SQLSTATE
class 23 (integrity constraint violation), but this is likely to be expandedin future.
There is an older function
elog
that is still heavily used. An
elog
call:
elog(level, "format string", ...);
is exactly equivalent to:
ereport(level, (errmsg_internal("format string", ...)));
Notice that the SQLSTATE error code is always defaulted, and the message string is not subject to
translation. Therefore,
elog
should be usedonly for internal errors and low-leveldebug logging. Any
message that is likely to be of interest to ordinary users should go through
ereport
.Nonetheless,
there are enough internal“cannot happen” error checks in the system that
elog
is still widely used; it
is preferred for those messages for its notational simplicity.
Advice about writing good error messages can be found in Section 50.3.
50.3. Error Message Style Guide
This style guide is offered in the hope of maintaining a consistent, user-friendly style throughout all
the messages generated by PostgreSQL.
50.3.1. What Goes Where
The primary message should be short, factual, and avoid reference to implementation details such as
specific functionnames. “Short” means “should fit on one line under normalconditions”. Use a detail
1903
42
Chapter 50. PostgreSQL Coding Conventions
messageif needed tokeep the primary message short, or if youfeela need tomention implementation
details such as the particular system call that failed. Both primary and detail messages should be
factual. Use a hint message for suggestions about what to do to fix the problem, especially if the
suggestion might not always be applicable.
For example, instead of:
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long addendum that is basically a hint)
write:
Primary:
could not create shared memory segment: %m
Detail:
Failed syscall was shmget(key=%d, size=%u, 0%o).
Hint:
the addendum
Rationale: keeping the primary message short helps keepit tothe point, and lets clients lay out screen
space on the assumption that one line is enough for error messages. Detail and hint messages can be
relegated to a verbose mode, or perhaps a pop-up error-details window. Also, details and hints would
normallybe suppressed from the server logto save space. Reference toimplementation details is best
avoided since users don’t know the details anyway.
50.3.2. Formatting
Don’t put any specific assumptions about formatting into the message texts. Expect clients and the
server log to wrap lines to fit their own needs. In long messages, newline characters (\n) can be used
to indicate suggested paragraph breaks. Don’t end a message with a newline. Don’t use tabs or other
formatting characters. (In error context displays, newlines are automatically added to separate levels
of context such as function calls.)
Rationale: Messages are not necessarily displayed on terminal-type displays. In GUI displays or
browsers these formatting instructions are at best ignored.
50.3.3. Quotation Marks
English text should use double quotes when quoting is appropriate. Text in other languages should
consistently use one kind of quotes that is consistent with publishing customs and computer output of
other programs.
Rationale: The choice of double quotes over single quotes is somewhat arbitrary, but tends to be the
preferred use. Some have suggested choosing the kind of quotes depending on the type of object
according to SQL conventions (namely, strings single quoted, identifiers double quoted). But this is
alanguage-internal technical issue that many users aren’t even familiar with, it won’t scale to other
kinds of quoted terms, it doesn’t translate to other languages, and it’s pretty pointless, too.
50.3.4. Use of Quotes
Use quotes always to delimit file names, user-supplied identifiers, and other variables that might
containwords. Donot use them tomarkup variables thatwill notcontainwords (for example, operator
names).
1904
38
Chapter 50. PostgreSQL Coding Conventions
There are functions in the backend that will double-quote their own output at need (for example,
format_type_be()
). Do not put additional quotes around the output of such functions.
Rationale: Objects can have names that create ambiguitywhen embedded in a message. Be consistent
about denotingwhere aplugged-in namestarts andends. Butdon’t clutter messages withunnecessary
or duplicate quote marks.
50.3.5. Grammar and Punctuation
The rules are different for primary error messages and for detail/hint messages:
Primaryerror messages: Do notcapitalize the first letter. Do not end a message with a period. Do not
even think about ending a message with an exclamation point.
Detail and hint messages: Use complete sentences, and end each with a period. Capitalize the first
word of sentences. Put twospaces after the period if another sentence follows (for English text; might
be inappropriate in other languages).
Error context strings: Donot capitalize the first letter and donot end the string with a period. Context
strings should normally not be complete sentences.
Rationale: Avoiding punctuation makes it easier for client applications to embed the message into a
variety of grammatical contexts. Often, primary messages are not grammatically complete sentences
anyway. (And if they’re long enough to be more than one sentence, they should be split into primary
and detail parts.) However, detail and hint messages are longer and might need to include multiple
sentences. For consistency, they should follow complete-sentence style even when there’s only one
sentence.
50.3.6. Upper Case vs. Lower Case
Use lower case for message wording, including the first letter of a primary error message. Use upper
case for SQL commands and key words if they appear in the message.
Rationale: It’s easier to make everything look more consistent this way, since some messages are
complete sentences and some not.
50.3.7. Avoid Passive Voice
Use the active voice. Use complete sentences when there is an acting subject (“A could not do B”).
Use telegram style without subject if the subject would be the program itself; do not use “I” for the
program.
Rationale: The program is not human. Don’t pretend otherwise.
50.3.8. Present vs. Past Tense
Use past tense if an attempt to do something failed, but could perhaps succeed next time (perhaps
after fixing some problem). Use present tense if the failure is certainly permanent.
There is a nontrivial semantic difference between sentences of the form:
could not open file "%s": %m
1905
33
Chapter 50. PostgreSQL Coding Conventions
and:
cannot open file "%s"
The first one means thatthe attempt toopenthe file failed. The message should give a reason, such as
“disk full” or “file doesn’t exist”. The past tense is appropriate because next time the disk might not
be full anymore or the file in question might exist.
The second form indicates that the functionality of opening the named file does not exist at all in the
program, or that it’s conceptually impossible. The present tense is appropriate because the condition
will persist indefinitely.
Rationale: Granted, the average user will not be able to draw great conclusions merely from the tense
of the message, but since the language provides us with a grammar we should use it correctly.
50.3.9. Type of the Object
When citing the name of an object, state what kind of object it is.
Rationale: Otherwise no one will know what “foo.bar.baz” refers to.
50.3.10. Brackets
Square brackets are only to be used (1) in command synopses to denote optional arguments, or (2) to
denote an array subscript.
Rationale: Anything else does not correspond to widely-known customary usage and will confuse
people.
50.3.11. Assembling Error Messages
When a message includes text that is generated elsewhere, embed it in this style:
could not open file %s: %m
Rationale: It would be difficult to accountfor all possible error codes to paste this into asingle smooth
sentence, so some sort of punctuation is needed. Putting the embedded text in parentheses has also
been suggested, but it’s unnatural if the embedded text is likely to be the most important part of the
message, as is often the case.
50.3.12. Reasons for Errors
Messages should always state the reason why an error occurred. For example:
BAD:
could not open file %s
BETTER: could not open file %s (I/O failure)
If no reason is knownyou better fix the code.
1906
42
Chapter 50. PostgreSQL Coding Conventions
50.3.13. Function Names
Don’t include the name of the reporting routine in the error text. We have other mechanisms for
finding that out when needed, and for most users it’s not helpful information. If the error text doesn’t
make as much sense without the function name, reword it.
BAD:
pg_atoi: error in "z": cannot parse "z"
BETTER: invalid input syntax for integer: "z"
Avoid mentioning called function names, either; instead say what the code was trying to do:
BAD:
open() failed: %m
BETTER: could not open file %s: %m
If it really seems necessary, mention the system call in the detail message. (In some cases, providing
the actual values passed to the system call might be appropriate information for the detail message.)
Rationale: Users don’t know what all those functions do.
50.3.14. Tricky Words to Avoid
Unable. “Unable” is nearly the passive voice. Better use “cannot” or “could not”, as appropriate.
Bad. Error messages like “bad result” are really hard to interpret intelligently. It’s better to write why
the result is “bad”, e.g., “invalid format”.
Illegal. “Illegal” stands for a violation of the law, the rest is “invalid”. Better yet, say why it’s invalid.
Unknown. Try to avoid “unknown”. Consider “error: unknown response”. If you don’t know what
the response is, how do you know it’s erroneous? “Unrecognized” is often a better choice. Also, be
sure to include the value being complained of.
BAD:
unknown node type
BETTER: unrecognized node type: 42
Find vs. Exists. If the program uses a nontrivial algorithm to locate a resource (e.g., a path search)
and that algorithm fails, it is fair to say that the program couldn’t “find” the resource. If, on the other
hand, the expected location of the resource is known but the program cannot access it there then say
that the resource doesn’t “exist”. Using “find” in this case sounds weak and confuses the issue.
May vs. Can vs. Might. “May” suggests permission (e.g., "You may borrow my rake."), and has
little use in documentation or error messages. “Can” suggests ability (e.g., "I can lift that log."), and
“might” suggests possibility (e.g., "It might rain today."). Using the proper word clarifies meaning
and assists translation.
Contractions. Avoid contractions, like “can’t”; use “cannot” instead.
50.3.15. Proper Spelling
Spell out words in full. For instance, avoid:
•
spec
•
stats
1907
Documents you may be interested
Documents you may be interested
