begriffs open source - ai-pg/blob - full-docs/txt/error-message-reporting.txt

   1
   2 55.2. Reporting Errors Within the Server #
   3
   4    Error, warning, and log messages generated within the server code
   5    should be created using ereport, or its older cousin elog. The use of
   6    this function is complex enough to require some explanation.
   7
   8    There are two required elements for every message: a severity level
   9    (ranging from DEBUG to PANIC, defined in src/include/utils/elog.h) and
  10    a primary message text. In addition there are optional elements, the
  11    most common of which is an error identifier code that follows the SQL
  12    spec's SQLSTATE conventions. ereport itself is just a shell macro that
  13    exists mainly for the syntactic convenience of making message
  14    generation look like a single function call in the C source code. The
  15    only parameter accepted directly by ereport is the severity level. The
  16    primary message text and any optional message elements are generated by
  17    calling auxiliary functions, such as errmsg, within the ereport call.
  18
  19    A typical call to ereport might look like this:
  20 ereport(ERROR,
  21         errcode(ERRCODE_DIVISION_BY_ZERO),
  22         errmsg("division by zero"));
  23
  24    This specifies error severity level ERROR (a run-of-the-mill error).
  25    The errcode call specifies the SQLSTATE error code using a macro
  26    defined in src/include/utils/errcodes.h. The errmsg call provides the
  27    primary message text.
  28
  29    You will also frequently see this older style, with an extra set of
  30    parentheses surrounding the auxiliary function calls:
  31 ereport(ERROR,
  32         (errcode(ERRCODE_DIVISION_BY_ZERO),
  33          errmsg("division by zero")));
  34
  35    The extra parentheses were required before PostgreSQL version 12, but
  36    are now optional.
  37
  38    Here is a more complex example:
  39 ereport(ERROR,
  40         errcode(ERRCODE_AMBIGUOUS_FUNCTION),
  41         errmsg("function %s is not unique",
  42                func_signature_string(funcname, nargs,
  43                                      NIL, actual_arg_types)),
  44         errhint("Unable to choose a best candidate function. "
  45                 "You might need to add explicit typecasts."));
  46
  47    This illustrates the use of format codes to embed run-time values into
  48    a message text. Also, an optional “hint” message is provided. The
  49    auxiliary function calls can be written in any order, but
  50    conventionally errcode and errmsg appear first.
  51
  52    If the severity level is ERROR or higher, ereport aborts execution of
  53    the current query and does not return to the caller. If the severity
  54    level is lower than ERROR, ereport returns normally.
  55
  56    The available auxiliary routines for ereport are:
  57      * errcode(sqlerrcode) specifies the SQLSTATE error identifier code
  58        for the condition. If this routine is not called, the error
  59        identifier defaults to ERRCODE_INTERNAL_ERROR when the error
  60        severity level is ERROR or higher, ERRCODE_WARNING when the error
  61        level is WARNING, otherwise (for NOTICE and below)
  62        ERRCODE_SUCCESSFUL_COMPLETION. While these defaults are often
  63        convenient, always think whether they are appropriate before
  64        omitting the errcode() call.
  65      * errmsg(const char *msg, ...) specifies the primary error message
  66        text, and possibly run-time values to insert into it. Insertions
  67        are specified by sprintf-style format codes. In addition to the
  68        standard format codes accepted by sprintf, the format code %m can
  69        be used to insert the error message returned by strerror for the
  70        current value of errno. ^[18] %m does not require any corresponding
  71        entry in the parameter list for errmsg. Note that the message
  72        string will be run through gettext for possible localization before
  73        format codes are processed.
  74      * errmsg_internal(const char *msg, ...) is the same as errmsg, except
  75        that the message string will not be translated nor included in the
  76        internationalization message dictionary. This should be used for
  77        “cannot happen” cases that are probably not worth expending
  78        translation effort on.
  79      * errmsg_plural(const char *fmt_singular, const char *fmt_plural,
  80        unsigned long n, ...) is like errmsg, but with support for various
  81        plural forms of the message. fmt_singular is the English singular
  82        format, fmt_plural is the English plural format, n is the integer
  83        value that determines which plural form is needed, and the
  84        remaining arguments are formatted according to the selected format
  85        string. For more information see Section 56.2.2.
  86      * errdetail(const char *msg, ...) supplies an optional “detail”
  87        message; this is to be used when there is additional information
  88        that seems inappropriate to put in the primary message. The message
  89        string is processed in just the same way as for errmsg.
  90      * errdetail_internal(const char *msg, ...) is the same as errdetail,
  91        except that the message string will not be translated nor included
  92        in the internationalization message dictionary. This should be used
  93        for detail messages that are not worth expending translation effort
  94        on, for instance because they are too technical to be useful to
  95        most users.
  96      * errdetail_plural(const char *fmt_singular, const char *fmt_plural,
  97        unsigned long n, ...) is like errdetail, but with support for
  98        various plural forms of the message. For more information see
  99        Section 56.2.2.
 100      * errdetail_log(const char *msg, ...) is the same as errdetail except
 101        that this string goes only to the server log, never to the client.
 102        If both errdetail (or one of its equivalents above) and
 103        errdetail_log are used then one string goes to the client and the
 104        other to the log. This is useful for error details that are too
 105        security-sensitive or too bulky to include in the report sent to
 106        the client.
 107      * errdetail_log_plural(const char *fmt_singular, const char
 108        *fmt_plural, unsigned long n, ...) is like errdetail_log, but with
 109        support for various plural forms of the message. For more
 110        information see Section 56.2.2.
 111      * errhint(const char *msg, ...) supplies an optional “hint” message;
 112        this is to be used when offering suggestions about how to fix the
 113        problem, as opposed to factual details about what went wrong. The
 114        message string is processed in just the same way as for errmsg.
 115      * errhint_plural(const char *fmt_singular, const char *fmt_plural,
 116        unsigned long n, ...) is like errhint, but with support for various
 117        plural forms of the message. For more information see
 118        Section 56.2.2.
 119      * errcontext(const char *msg, ...) is not normally called directly
 120        from an ereport message site; rather it is used in
 121        error_context_stack callback functions to provide information about
 122        the context in which an error occurred, such as the current
 123        location in a PL function. The message string is processed in just
 124        the same way as for errmsg. Unlike the other auxiliary functions,
 125        this can be called more than once per ereport call; the successive
 126        strings thus supplied are concatenated with separating newlines.
 127      * errposition(int cursorpos) specifies the textual location of an
 128        error within a query string. Currently it is only useful for errors
 129        detected in the lexical and syntactic analysis phases of query
 130        processing.
 131      * errtable(Relation rel) specifies a relation whose name and schema
 132        name should be included as auxiliary fields in the error report.
 133      * errtablecol(Relation rel, int attnum) specifies a column whose
 134        name, table name, and schema name should be included as auxiliary
 135        fields in the error report.
 136      * errtableconstraint(Relation rel, const char *conname) specifies a
 137        table constraint whose name, table name, and schema name should be
 138        included as auxiliary fields in the error report. Indexes should be
 139        considered to be constraints for this purpose, whether or not they
 140        have an associated pg_constraint entry. Be careful to pass the
 141        underlying heap relation, not the index itself, as rel.
 142      * errdatatype(Oid datatypeOid) specifies a data type whose name and
 143        schema name should be included as auxiliary fields in the error
 144        report.
 145      * errdomainconstraint(Oid datatypeOid, const char *conname) specifies
 146        a domain constraint whose name, domain name, and schema name should
 147        be included as auxiliary fields in the error report.
 148      * errcode_for_file_access() is a convenience function that selects an
 149        appropriate SQLSTATE error identifier for a failure in a
 150        file-access-related system call. It uses the saved errno to
 151        determine which error code to generate. Usually this should be used
 152        in combination with %m in the primary error message text.
 153      * errcode_for_socket_access() is a convenience function that selects
 154        an appropriate SQLSTATE error identifier for a failure in a
 155        socket-related system call.
 156      * errhidestmt(bool hide_stmt) can be called to specify suppression of
 157        the STATEMENT: portion of a message in the postmaster log.
 158        Generally this is appropriate if the message text includes the
 159        current statement already.
 160      * errhidecontext(bool hide_ctx) can be called to specify suppression
 161        of the CONTEXT: portion of a message in the postmaster log. This
 162        should only be used for verbose debugging messages where the
 163        repeated inclusion of context would bloat the log too much.
 164
 165 Note
 166
 167    At most one of the functions errtable, errtablecol, errtableconstraint,
 168    errdatatype, or errdomainconstraint should be used in an ereport call.
 169    These functions exist to allow applications to extract the name of a
 170    database object associated with the error condition without having to
 171    examine the potentially-localized error message text. These functions
 172    should be used in error reports for which it's likely that applications
 173    would wish to have automatic error handling. As of PostgreSQL 9.3,
 174    complete coverage exists only for errors in SQLSTATE class 23
 175    (integrity constraint violation), but this is likely to be expanded in
 176    future.
 177
 178    There is an older function elog that is still heavily used. An elog
 179    call:
 180 elog(level, "format string", ...);
 181
 182    is exactly equivalent to:
 183 ereport(level, errmsg_internal("format string", ...));
 184
 185    Notice that the SQLSTATE error code is always defaulted, and the
 186    message string is not subject to translation. Therefore, elog should be
 187    used only for internal errors and low-level debug logging. Any message
 188    that is likely to be of interest to ordinary users should go through
 189    ereport. Nonetheless, there are enough internal “cannot happen” error
 190    checks in the system that elog is still widely used; it is preferred
 191    for those messages for its notational simplicity.
 192
 193    Advice about writing good error messages can be found in Section 55.3.
 194
 195    ^[18] That is, the value that was current when the ereport call was
 196    reached; changes of errno within the auxiliary reporting routines will
 197    not affect it. That would not be true if you were to write
 198    strerror(errno) explicitly in errmsg's parameter list; accordingly, do
 199    not do so.