PostgreSQL 9.3.25 Documentation | ||||
---|---|---|---|---|
Prev | Up | Chapter 49. PostgreSQL Coding Conventions | Next |
Error, warning, and log messages generated within the server
code should be created using ereport
,
or its older cousin elog
. The use of
this function is complex enough to require some explanation.
There are two required elements for every message: a severity
level (ranging from DEBUG to PANIC) and a primary message text. In addition there
are optional elements, the most common of which is an error
identifier code that follows the SQL spec's SQLSTATE conventions.
ereport
itself is just a shell
function, that exists mainly for the syntactic convenience of
making message generation look like a function call in the C source
code. The only parameter accepted directly by ereport
is the severity level. The primary
message text and any optional message elements are generated by
calling auxiliary functions, such as errmsg
, within the ereport
call.
A typical call to ereport
might
look like this:
ereport(ERROR, (errcode(ERRCODE_DIVISION_BY_ZERO), errmsg("division by zero")));
This specifies error severity level ERROR (a run-of-the-mill error). The errcode
call specifies the SQLSTATE error code
using a macro defined in src/include/utils/errcodes.h. The errmsg
call provides the primary message text.
Notice the extra set of parentheses surrounding the auxiliary
function calls — these are annoying but syntactically
necessary.
Here is a more complex example:
ereport(ERROR, (errcode(ERRCODE_AMBIGUOUS_FUNCTION), errmsg("function %s is not unique", func_signature_string(funcname, nargs, NIL, actual_arg_types)), errhint("Unable to choose a best candidate function. " "You might need to add explicit typecasts.")));
This illustrates the use of format codes to embed run-time values into a message text. Also, an optional "hint" message is provided.
The available auxiliary routines for ereport
are:
errcode(sqlerrcode)
specifies the
SQLSTATE error identifier code for the condition. If this routine
is not called, the error identifier defaults to ERRCODE_INTERNAL_ERROR when the error severity level
is ERROR or higher, ERRCODE_WARNING when the error level is WARNING, otherwise (for NOTICE and below) ERRCODE_SUCCESSFUL_COMPLETION. While these defaults
are often convenient, always think whether they are appropriate
before omitting the errcode()
call.
errmsg(const char *msg, ...)
specifies the primary error message text, and possibly run-time
values to insert into it. Insertions are specified by sprintf
-style format codes. In addition to the
standard format codes accepted by sprintf
, the format code %m can be used to insert the error message returned
by strerror
for the current value of
errno. [1] %m does not
require any corresponding entry in the parameter list for
errmsg
. Note that the message string
will be run through gettext
for
possible localization before format codes are processed.
errmsg_internal(const char *msg,
...)
is the same as errmsg
,
except that the message string will not be translated nor included
in the internationalization message 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 50.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
processed in 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
50.2.2.
errdetail_log(const char *msg,
...)
is the same as errdetail
except that this string goes only to the 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 that are too security-sensitive or too bulky to include in
the report sent to the client.
errhint(const char *msg, ...)
supplies an optional "hint" message;
this is to be used when 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
message 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 functions,
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)
specifies a
relation whose name and schema name should be included 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 should be 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.
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 function that selects an appropriate SQLSTATE error
identifier for a failure in a file-access-related system call. It
uses the saved errno to determine 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 SQLSTATE error
identifier for a failure in a socket-related system call.
errhidestmt(bool hide_stmt)
can be
called to specify suppression of the STATEMENT: portion 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
, orerrdomainconstraint
should be used in anereport
call. These functions exist to allow applications to extract the name of a database object associated with the error condition without having to examine the potentially-localized error message text. These functions should be 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 expanded in 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 used only for internal
errors and low-level debug 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 49.3.
[1] |
That is, the value that was current when the |