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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.2. Reporting Errors Within the Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="source-format.html" title="55.1. Formatting" /><link rel="next" href="error-style-guide.html" title="55.3. Error Message Style Guide" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.2. Reporting Errors Within the Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source-format.html" title="55.1. Formatting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 55. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="error-style-guide.html" title="55.3. Error Message Style Guide">Next</a></td></tr></table><hr /></div><div class="sect1" id="ERROR-MESSAGE-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.2. Reporting Errors Within the Server <a href="#ERROR-MESSAGE-REPORTING" class="id_link">#</a></h2></div></div></div><a id="id-1.10.7.3.2" class="indexterm"></a><a id="id-1.10.7.3.3" class="indexterm"></a><p>
   3     Error, warning, and log messages generated within the server code
   4     should be created using <code class="function">ereport</code>, or its older cousin
   5     <code class="function">elog</code>.  The use of this function is complex enough to
   6     require some explanation.
   7    </p><p>
   8     There are two required elements for every message: a severity level
   9     (ranging from <code class="literal">DEBUG</code> to <code class="literal">PANIC</code>, defined
  10     in <code class="filename">src/include/utils/elog.h</code>) and a primary
  11     message text.  In addition there are optional elements, the most
  12     common of which is an error identifier code that follows the SQL spec's
  13     SQLSTATE conventions.
  14     <code class="function">ereport</code> itself is just a shell macro that exists
  15     mainly for the syntactic convenience of making message generation
  16     look like a single function call in the C source code.  The only parameter
  17     accepted directly by <code class="function">ereport</code> is the severity level.
  18     The primary message text and any optional message elements are
  19     generated by calling auxiliary functions, such as <code class="function">errmsg</code>,
  20     within the <code class="function">ereport</code> call.
  21    </p><p>
  22     A typical call to <code class="function">ereport</code> might look like this:
  23 </p><pre class="programlisting">
  24 ereport(ERROR,
  25         errcode(ERRCODE_DIVISION_BY_ZERO),
  26         errmsg("division by zero"));
  27 </pre><p>
  28     This specifies error severity level <code class="literal">ERROR</code> (a run-of-the-mill
  29     error).  The <code class="function">errcode</code> call specifies the SQLSTATE error code
  30     using a macro defined in <code class="filename">src/include/utils/errcodes.h</code>.  The
  31     <code class="function">errmsg</code> call provides the primary message text.
  32    </p><p>
  33     You will also frequently see this older style, with an extra set of
  34     parentheses surrounding the auxiliary function calls:
  35 </p><pre class="programlisting">
  36 ereport(ERROR,
  37         (errcode(ERRCODE_DIVISION_BY_ZERO),
  38          errmsg("division by zero")));
  39 </pre><p>
  40     The extra parentheses were required
  41     before <span class="productname">PostgreSQL</span> version 12, but are now
  42     optional.
  43    </p><p>
  44     Here is a more complex example:
  45 </p><pre class="programlisting">
  46 ereport(ERROR,
  47         errcode(ERRCODE_AMBIGUOUS_FUNCTION),
  48         errmsg("function %s is not unique",
  49                func_signature_string(funcname, nargs,
  50                                      NIL, actual_arg_types)),
  51         errhint("Unable to choose a best candidate function. "
  52                 "You might need to add explicit typecasts."));
  53 </pre><p>
  54     This illustrates the use of format codes to embed run-time values into
  55     a message text.  Also, an optional <span class="quote">“<span class="quote">hint</span>”</span> message is provided.
  56     The auxiliary function calls can be written in any order, but
  57     conventionally <code class="function">errcode</code>
  58     and <code class="function">errmsg</code> appear first.
  59    </p><p>
  60     If the severity level is <code class="literal">ERROR</code> or higher,
  61     <code class="function">ereport</code> aborts execution of the current query
  62     and does not return to the caller. If the severity level is
  63     lower than <code class="literal">ERROR</code>, <code class="function">ereport</code> returns normally.
  64    </p><p>
  65     The available auxiliary routines for <code class="function">ereport</code> are:
  66   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  67      <code class="function">errcode(sqlerrcode)</code> specifies the SQLSTATE error identifier
  68      code for the condition.  If this routine is not called, the error
  69      identifier defaults to
  70      <code class="literal">ERRCODE_INTERNAL_ERROR</code> when the error severity level is
  71      <code class="literal">ERROR</code> or higher, <code class="literal">ERRCODE_WARNING</code> when the
  72      error level is <code class="literal">WARNING</code>, otherwise (for <code class="literal">NOTICE</code>
  73      and below) <code class="literal">ERRCODE_SUCCESSFUL_COMPLETION</code>.
  74      While these defaults are often convenient, always think whether they
  75      are appropriate before omitting the <code class="function">errcode()</code> call.
  76     </p></li><li class="listitem"><p>
  77      <code class="function">errmsg(const char *msg, ...)</code> specifies the primary error
  78      message text, and possibly run-time values to insert into it.  Insertions
  79      are specified by <code class="function">sprintf</code>-style format codes.  In addition to
  80      the standard format codes accepted by <code class="function">sprintf</code>, the format
  81      code <code class="literal">%m</code> can be used to insert the error message returned
  82      by <code class="function">strerror</code> for the current value of <code class="literal">errno</code>.
  83      <a href="#ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><sup class="footnote" id="id-1.10.7.3.10.2.2.1.7">[18]</sup></a>
  84      <code class="literal">%m</code> does not require any
  85      corresponding entry in the parameter list for <code class="function">errmsg</code>.
  86      Note that the message string will be run through <code class="function">gettext</code>
  87      for possible localization before format codes are processed.
  88     </p></li><li class="listitem"><p>
  89      <code class="function">errmsg_internal(const char *msg, ...)</code> is the same as
  90      <code class="function">errmsg</code>, except that the message string will not be
  91      translated nor included in the internationalization message dictionary.
  92      This should be used for <span class="quote">“<span class="quote">cannot happen</span>”</span> cases that are probably
  93      not worth expending translation effort on.
  94     </p></li><li class="listitem"><p>
  95      <code class="function">errmsg_plural(const char *fmt_singular, const char *fmt_plural,
  96      unsigned long n, ...)</code> is like <code class="function">errmsg</code>, but with
  97      support for various plural forms of the message.
  98      <em class="replaceable"><code>fmt_singular</code></em> is the English singular format,
  99      <em class="replaceable"><code>fmt_plural</code></em> is the English plural format,
 100      <em class="replaceable"><code>n</code></em> is the integer value that determines which plural
 101      form is needed, and the remaining arguments are formatted according
 102      to the selected format string.  For more information see
 103      <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="56.2.2. Message-Writing Guidelines">Section 56.2.2</a>.
 104     </p></li><li class="listitem"><p>
 105      <code class="function">errdetail(const char *msg, ...)</code> supplies an optional
 106      <span class="quote">“<span class="quote">detail</span>”</span> message; this is to be used when there is additional
 107      information that seems inappropriate to put in the primary message.
 108      The message string is processed in just the same way as for
 109      <code class="function">errmsg</code>.
 110     </p></li><li class="listitem"><p>
 111      <code class="function">errdetail_internal(const char *msg, ...)</code> is the same
 112      as <code class="function">errdetail</code>, except that the message string will not be
 113      translated nor included in the internationalization message dictionary.
 114      This should be used for detail messages that are not worth expending
 115      translation effort on, for instance because they are too technical to be
 116      useful to most users.
 117     </p></li><li class="listitem"><p>
 118      <code class="function">errdetail_plural(const char *fmt_singular, const char *fmt_plural,
 119      unsigned long n, ...)</code> is like <code class="function">errdetail</code>, but with
 120      support for various plural forms of the message.
 121      For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="56.2.2. Message-Writing Guidelines">Section 56.2.2</a>.
 122     </p></li><li class="listitem"><p>
 123      <code class="function">errdetail_log(const char *msg, ...)</code> is the same as
 124      <code class="function">errdetail</code> except that this string goes only to the server
 125      log, never to the client.  If both <code class="function">errdetail</code> (or one of
 126      its equivalents above) and
 127      <code class="function">errdetail_log</code> are used then one string goes to the client
 128      and the other to the log.  This is useful for error details that are
 129      too security-sensitive or too bulky to include in the report
 130      sent to the client.
 131     </p></li><li class="listitem"><p>
 132      <code class="function">errdetail_log_plural(const char *fmt_singular, const char
 133      *fmt_plural, unsigned long n, ...)</code> is like
 134      <code class="function">errdetail_log</code>, but with support for various plural forms of
 135      the message.
 136      For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="56.2.2. Message-Writing Guidelines">Section 56.2.2</a>.
 137     </p></li><li class="listitem"><p>
 138      <code class="function">errhint(const char *msg, ...)</code> supplies an optional
 139      <span class="quote">“<span class="quote">hint</span>”</span> message; this is to be used when offering suggestions
 140      about how to fix the problem, as opposed to factual details about
 141      what went wrong.
 142      The message string is processed in just the same way as for
 143      <code class="function">errmsg</code>.
 144     </p></li><li class="listitem"><p>
 145      <code class="function">errhint_plural(const char *fmt_singular, const char *fmt_plural,
 146      unsigned long n, ...)</code> is like <code class="function">errhint</code>, but with
 147      support for various plural forms of the message.
 148      For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="56.2.2. Message-Writing Guidelines">Section 56.2.2</a>.
 149     </p></li><li class="listitem"><p>
 150      <code class="function">errcontext(const char *msg, ...)</code> is not normally called
 151      directly from an <code class="function">ereport</code> message site; rather it is used
 152      in <code class="literal">error_context_stack</code> callback functions to provide
 153      information about the context in which an error occurred, such as the
 154      current location in a PL function.
 155      The message string is processed in just the same way as for
 156      <code class="function">errmsg</code>.  Unlike the other auxiliary functions, this can
 157      be called more than once per <code class="function">ereport</code> call; the successive
 158      strings thus supplied are concatenated with separating newlines.
 159     </p></li><li class="listitem"><p>
 160      <code class="function">errposition(int cursorpos)</code> specifies the textual location
 161      of an error within a query string.  Currently it is only useful for
 162      errors detected in the lexical and syntactic analysis phases of
 163      query processing.
 164     </p></li><li class="listitem"><p>
 165      <code class="function">errtable(Relation rel)</code> specifies a relation whose
 166      name and schema name should be included as auxiliary fields in the error
 167      report.
 168     </p></li><li class="listitem"><p>
 169      <code class="function">errtablecol(Relation rel, int attnum)</code> specifies
 170      a column whose name, table name, and schema name should be included as
 171      auxiliary fields in the error report.
 172     </p></li><li class="listitem"><p>
 173      <code class="function">errtableconstraint(Relation rel, const char *conname)</code>
 174      specifies a table constraint whose name, table name, and schema name
 175      should be included as auxiliary fields in the error report.  Indexes
 176      should be considered to be constraints for this purpose, whether or
 177      not they have an associated <code class="structname">pg_constraint</code> entry.  Be
 178      careful to pass the underlying heap relation, not the index itself, as
 179      <code class="literal">rel</code>.
 180     </p></li><li class="listitem"><p>
 181      <code class="function">errdatatype(Oid datatypeOid)</code> specifies a data
 182      type whose name and schema name should be included as auxiliary fields
 183      in the error report.
 184     </p></li><li class="listitem"><p>
 185      <code class="function">errdomainconstraint(Oid datatypeOid, const char *conname)</code>
 186      specifies a domain constraint whose name, domain name, and schema name
 187      should be included as auxiliary fields in the error report.
 188     </p></li><li class="listitem"><p>
 189      <code class="function">errcode_for_file_access()</code> is a convenience function that
 190      selects an appropriate SQLSTATE error identifier for a failure in a
 191      file-access-related system call.  It uses the saved
 192      <code class="literal">errno</code> to determine which error code to generate.
 193      Usually this should be used in combination with <code class="literal">%m</code> in the
 194      primary error message text.
 195     </p></li><li class="listitem"><p>
 196      <code class="function">errcode_for_socket_access()</code> is a convenience function that
 197      selects an appropriate SQLSTATE error identifier for a failure in a
 198      socket-related system call.
 199     </p></li><li class="listitem"><p>
 200      <code class="function">errhidestmt(bool hide_stmt)</code> can be called to specify
 201      suppression of the <code class="literal">STATEMENT:</code> portion of a message in the
 202      postmaster log.  Generally this is appropriate if the message text
 203      includes the current statement already.
 204     </p></li><li class="listitem"><p>
 205      <code class="function">errhidecontext(bool hide_ctx)</code> can be called to
 206      specify suppression of the <code class="literal">CONTEXT:</code> portion of a message in
 207      the postmaster log.  This should only be used for verbose debugging
 208      messages where the repeated inclusion of context would bloat the log
 209      too much.
 210     </p></li></ul></div><p>
 211    </p><div class="note"><h3 class="title">Note</h3><p>
 212      At most one of the functions <code class="function">errtable</code>,
 213      <code class="function">errtablecol</code>, <code class="function">errtableconstraint</code>,
 214      <code class="function">errdatatype</code>, or <code class="function">errdomainconstraint</code> should
 215      be used in an <code class="function">ereport</code> call.  These functions exist to
 216      allow applications to extract the name of a database object associated
 217      with the error condition without having to examine the
 218      potentially-localized error message text.
 219      These functions should be used in error reports for which it's likely
 220      that applications would wish to have automatic error handling.  As of
 221      <span class="productname">PostgreSQL</span> 9.3, complete coverage exists only for
 222      errors in SQLSTATE class 23 (integrity constraint violation), but this
 223      is likely to be expanded in future.
 224     </p></div><p>
 225     There is an older function <code class="function">elog</code> that is still heavily used.
 226     An <code class="function">elog</code> call:
 227 </p><pre class="programlisting">
 228 elog(level, "format string", ...);
 229 </pre><p>
 230     is exactly equivalent to:
 231 </p><pre class="programlisting">
 232 ereport(level, errmsg_internal("format string", ...));
 233 </pre><p>
 234     Notice that the SQLSTATE error code is always defaulted, and the message
 235     string is not subject to translation.
 236     Therefore, <code class="function">elog</code> should be used only for internal errors and
 237     low-level debug logging.  Any message that is likely to be of interest to
 238     ordinary users should go through <code class="function">ereport</code>.  Nonetheless,
 239     there are enough internal <span class="quote">“<span class="quote">cannot happen</span>”</span> error checks in the
 240     system that <code class="function">elog</code> is still widely used; it is preferred for
 241     those messages for its notational simplicity.
 242    </p><p>
 243     Advice about writing good error messages can be found in
 244     <a class="xref" href="error-style-guide.html" title="55.3. Error Message Style Guide">Section 55.3</a>.
 245    </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><p><a href="#id-1.10.7.3.10.2.2.1.7" class="para"><sup class="para">[18] </sup></a>
 246        That is, the value that was current when the <code class="function">ereport</code> call
 247        was reached; changes of <code class="literal">errno</code> within the auxiliary reporting
 248        routines will not affect it.  That would not be true if you were to
 249        write <code class="literal">strerror(errno)</code> explicitly in <code class="function">errmsg</code>'s
 250        parameter list; accordingly, do not do so.
 251       </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source-format.html" title="55.1. Formatting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 55. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="error-style-guide.html" title="55.3. Error Message Style Guide">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.1. Formatting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.3. Error Message Style Guide</td></tr></table></div></body></html>