summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/error-message-reporting.html
blob: 612044cbcdcfddcf38f195ff9e253b186fd0e9c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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>56.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="56.1. Formatting" /><link rel="next" href="error-style-guide.html" title="56.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">56.2. Reporting Errors Within the Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source-format.html" title="56.1. Formatting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.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">56.2. Reporting Errors Within the Server</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>
    Error, warning, and log messages generated within the server code
    should be created using <code class="function">ereport</code>, or its older cousin
    <code class="function">elog</code>.  The use of this function is complex enough to
    require some explanation.
   </p><p>
    There are two required elements for every message: a severity level
    (ranging from <code class="literal">DEBUG</code> to <code class="literal">PANIC</code>) 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.
    <code class="function">ereport</code> itself is just a shell macro that exists
    mainly for the syntactic convenience of making message generation
    look like a single function call in the C source code.  The only parameter
    accepted directly by <code class="function">ereport</code> is the severity level.
    The primary message text and any optional message elements are
    generated by calling auxiliary functions, such as <code class="function">errmsg</code>,
    within the <code class="function">ereport</code> call.
   </p><p>
    A typical call to <code class="function">ereport</code> might look like this:
</p><pre class="programlisting">
ereport(ERROR,
        errcode(ERRCODE_DIVISION_BY_ZERO),
        errmsg("division by zero"));
</pre><p>
    This specifies error severity level <code class="literal">ERROR</code> (a run-of-the-mill
    error).  The <code class="function">errcode</code> call specifies the SQLSTATE error code
    using a macro defined in <code class="filename">src/include/utils/errcodes.h</code>.  The
    <code class="function">errmsg</code> call provides the primary message text.
   </p><p>
    You will also frequently see this older style, with an extra set of
    parentheses surrounding the auxiliary function calls:
</p><pre class="programlisting">
ereport(ERROR,
        (errcode(ERRCODE_DIVISION_BY_ZERO),
         errmsg("division by zero")));
</pre><p>
    The extra parentheses were required
    before <span class="productname">PostgreSQL</span> version 12, but are now
    optional.
   </p><p>
    Here is a more complex example:
</p><pre class="programlisting">
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."));
</pre><p>
    This illustrates the use of format codes to embed run-time values into
    a message text.  Also, an optional <span class="quote"><span class="quote">hint</span></span> message is provided.
    The auxiliary function calls can be written in any order, but
    conventionally <code class="function">errcode</code>
    and <code class="function">errmsg</code> appear first.
   </p><p>
    If the severity level is <code class="literal">ERROR</code> or higher,
    <code class="function">ereport</code> aborts execution of the current query
    and does not return to the caller. If the severity level is
    lower than <code class="literal">ERROR</code>, <code class="function">ereport</code> returns normally.
   </p><p>
    The available auxiliary routines for <code class="function">ereport</code> are:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
     <code class="function">errcode(sqlerrcode)</code> specifies the SQLSTATE error identifier
     code for the condition.  If this routine is not called, the error
     identifier defaults to
     <code class="literal">ERRCODE_INTERNAL_ERROR</code> when the error severity level is
     <code class="literal">ERROR</code> or higher, <code class="literal">ERRCODE_WARNING</code> when the
     error level is <code class="literal">WARNING</code>, otherwise (for <code class="literal">NOTICE</code>
     and below) <code class="literal">ERRCODE_SUCCESSFUL_COMPLETION</code>.
     While these defaults are often convenient, always think whether they
     are appropriate before omitting the <code class="function">errcode()</code> call.
    </p></li><li class="listitem"><p>
     <code class="function">errmsg(const char *msg, ...)</code> specifies the primary error
     message text, and possibly run-time values to insert into it.  Insertions
     are specified by <code class="function">sprintf</code>-style format codes.  In addition to
     the standard format codes accepted by <code class="function">sprintf</code>, the format
     code <code class="literal">%m</code> can be used to insert the error message returned
     by <code class="function">strerror</code> for the current value of <code class="literal">errno</code>.
     <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">[16]</sup></a>
     <code class="literal">%m</code> does not require any
     corresponding entry in the parameter list for <code class="function">errmsg</code>.
     Note that the message string will be run through <code class="function">gettext</code>
     for possible localization before format codes are processed.
    </p></li><li class="listitem"><p>
     <code class="function">errmsg_internal(const char *msg, ...)</code> is the same as
     <code class="function">errmsg</code>, except that the message string will not be
     translated nor included in the internationalization message dictionary.
     This should be used for <span class="quote"><span class="quote">cannot happen</span></span> cases that are probably
     not worth expending translation effort on.
    </p></li><li class="listitem"><p>
     <code class="function">errmsg_plural(const char *fmt_singular, const char *fmt_plural,
     unsigned long n, ...)</code> is like <code class="function">errmsg</code>, but with
     support for various plural forms of the message.
     <em class="replaceable"><code>fmt_singular</code></em> is the English singular format,
     <em class="replaceable"><code>fmt_plural</code></em> is the English plural format,
     <em class="replaceable"><code>n</code></em> 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
     <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
    </p></li><li class="listitem"><p>
     <code class="function">errdetail(const char *msg, ...)</code> supplies an optional
     <span class="quote"><span class="quote">detail</span></span> 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
     <code class="function">errmsg</code>.
    </p></li><li class="listitem"><p>
     <code class="function">errdetail_internal(const char *msg, ...)</code> is the same
     as <code class="function">errdetail</code>, 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.
    </p></li><li class="listitem"><p>
     <code class="function">errdetail_plural(const char *fmt_singular, const char *fmt_plural,
     unsigned long n, ...)</code> is like <code class="function">errdetail</code>, but with
     support for various plural forms of the message.
     For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
    </p></li><li class="listitem"><p>
     <code class="function">errdetail_log(const char *msg, ...)</code> is the same as
     <code class="function">errdetail</code> except that this string goes only to the server
     log, never to the client.  If both <code class="function">errdetail</code> (or one of
     its equivalents above) and
     <code class="function">errdetail_log</code> 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.
    </p></li><li class="listitem"><p>
     <code class="function">errdetail_log_plural(const char *fmt_singular, const char
     *fmt_plural, unsigned long n, ...)</code> is like
     <code class="function">errdetail_log</code>, but with support for various plural forms of
     the message.
     For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
    </p></li><li class="listitem"><p>
     <code class="function">errhint(const char *msg, ...)</code> supplies an optional
     <span class="quote"><span class="quote">hint</span></span> 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
     <code class="function">errmsg</code>.
    </p></li><li class="listitem"><p>
     <code class="function">errhint_plural(const char *fmt_singular, const char *fmt_plural,
     unsigned long n, ...)</code> is like <code class="function">errhint</code>, but with
     support for various plural forms of the message.
     For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
    </p></li><li class="listitem"><p>
     <code class="function">errcontext(const char *msg, ...)</code> is not normally called
     directly from an <code class="function">ereport</code> message site; rather it is used
     in <code class="literal">error_context_stack</code> 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
     <code class="function">errmsg</code>.  Unlike the other auxiliary functions, this can
     be called more than once per <code class="function">ereport</code> call; the successive
     strings thus supplied are concatenated with separating newlines.
    </p></li><li class="listitem"><p>
     <code class="function">errposition(int cursorpos)</code> 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.
    </p></li><li class="listitem"><p>
     <code class="function">errtable(Relation rel)</code> specifies a relation whose
     name and schema name should be included as auxiliary fields in the error
     report.
    </p></li><li class="listitem"><p>
     <code class="function">errtablecol(Relation rel, int attnum)</code> specifies
     a column whose name, table name, and schema name should be included as
     auxiliary fields in the error report.
    </p></li><li class="listitem"><p>
     <code class="function">errtableconstraint(Relation rel, const char *conname)</code>
     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 <code class="structname">pg_constraint</code> entry.  Be
     careful to pass the underlying heap relation, not the index itself, as
     <code class="literal">rel</code>.
    </p></li><li class="listitem"><p>
     <code class="function">errdatatype(Oid datatypeOid)</code> specifies a data
     type whose name and schema name should be included as auxiliary fields
     in the error report.
    </p></li><li class="listitem"><p>
     <code class="function">errdomainconstraint(Oid datatypeOid, const char *conname)</code>
     specifies a domain constraint whose name, domain name, and schema name
     should be included as auxiliary fields in the error report.
    </p></li><li class="listitem"><p>
     <code class="function">errcode_for_file_access()</code> 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
     <code class="literal">errno</code> to determine which error code to generate.
     Usually this should be used in combination with <code class="literal">%m</code> in the
     primary error message text.
    </p></li><li class="listitem"><p>
     <code class="function">errcode_for_socket_access()</code> is a convenience function that
     selects an appropriate SQLSTATE error identifier for a failure in a
     socket-related system call.
    </p></li><li class="listitem"><p>
     <code class="function">errhidestmt(bool hide_stmt)</code> can be called to specify
     suppression of the <code class="literal">STATEMENT:</code> portion of a message in the
     postmaster log.  Generally this is appropriate if the message text
     includes the current statement already.
    </p></li><li class="listitem"><p>
     <code class="function">errhidecontext(bool hide_ctx)</code> can be called to
     specify suppression of the <code class="literal">CONTEXT:</code> portion of a message in
     the postmaster log.  This should only be used for verbose debugging
     messages where the repeated inclusion of context would bloat the log
     too much.
    </p></li></ul></div><p>
   </p><div class="note"><h3 class="title">Note</h3><p>
     At most one of the functions <code class="function">errtable</code>,
     <code class="function">errtablecol</code>, <code class="function">errtableconstraint</code>,
     <code class="function">errdatatype</code>, or <code class="function">errdomainconstraint</code> should
     be used in an <code class="function">ereport</code> 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
     <span class="productname">PostgreSQL</span> 9.3, complete coverage exists only for
     errors in SQLSTATE class 23 (integrity constraint violation), but this
     is likely to be expanded in future.
    </p></div><p>
    There is an older function <code class="function">elog</code> that is still heavily used.
    An <code class="function">elog</code> call:
</p><pre class="programlisting">
elog(level, "format string", ...);
</pre><p>
    is exactly equivalent to:
</p><pre class="programlisting">
ereport(level, errmsg_internal("format string", ...));
</pre><p>
    Notice that the SQLSTATE error code is always defaulted, and the message
    string is not subject to translation.
    Therefore, <code class="function">elog</code> 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 <code class="function">ereport</code>.  Nonetheless,
    there are enough internal <span class="quote"><span class="quote">cannot happen</span></span> error checks in the
    system that <code class="function">elog</code> is still widely used; it is preferred for
    those messages for its notational simplicity.
   </p><p>
    Advice about writing good error messages can be found in
    <a class="xref" href="error-style-guide.html" title="56.3. Error Message Style Guide">Section 56.3</a>.
   </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">[16] </sup></a>
       That is, the value that was current when the <code class="function">ereport</code> call
       was reached; changes of <code class="literal">errno</code> within the auxiliary reporting
       routines will not affect it.  That would not be true if you were to
       write <code class="literal">strerror(errno)</code> explicitly in <code class="function">errmsg</code>'s
       parameter list; accordingly, do not do so.
      </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="56.1. Formatting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.3. Error Message Style Guide">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.1. Formatting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.3. Error Message Style Guide</td></tr></table></div></body></html>