begriffs open source - ai-pg/blob - full-docs/html/plpgsql-errors-and-messages.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>41.9. Errors and Messages</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="plpgsql-transactions.html" title="41.8. Transaction Management" /><link rel="next" href="plpgsql-trigger.html" title="41.10. Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.9. Errors and Messages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-transactions.html" title="41.8. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 41. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</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="plpgsql-trigger.html" title="41.10. Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-ERRORS-AND-MESSAGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.9. Errors and Messages <a href="#PLPGSQL-ERRORS-AND-MESSAGES" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE">41.9.1. Reporting Errors and Messages</a></span></dt><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">41.9.2. Checking Assertions</a></span></dt></dl></div><div class="sect2" id="PLPGSQL-STATEMENTS-RAISE"><div class="titlepage"><div><div><h3 class="title">41.9.1. Reporting Errors and Messages <a href="#PLPGSQL-STATEMENTS-RAISE" class="id_link">#</a></h3></div></div></div><a id="id-1.8.8.11.2.2" class="indexterm"></a><a id="id-1.8.8.11.2.3" class="indexterm"></a><p>
   3     Use the <code class="command">RAISE</code> statement to report messages and
   4     raise errors.
   5
   6 </p><pre class="synopsis">
   7 RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] '<em class="replaceable"><code>format</code></em>' [<span class="optional">, <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>]</span>] [<span class="optional"> USING <em class="replaceable"><code>option</code></em> { = | := } <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
   8 RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] <em class="replaceable"><code>condition_name</code></em> [<span class="optional"> USING <em class="replaceable"><code>option</code></em> { = | := } <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
   9 RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] SQLSTATE '<em class="replaceable"><code>sqlstate</code></em>' [<span class="optional"> USING <em class="replaceable"><code>option</code></em> { = | := } <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
  10 RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] USING <em class="replaceable"><code>option</code></em> { = | := } <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>];
  11 RAISE ;
  12 </pre><p>
  13
  14     The <em class="replaceable"><code>level</code></em> option specifies
  15     the error severity.  Allowed levels are <code class="literal">DEBUG</code>,
  16     <code class="literal">LOG</code>, <code class="literal">INFO</code>,
  17     <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>,
  18     and <code class="literal">EXCEPTION</code>, with <code class="literal">EXCEPTION</code>
  19     being the default.
  20     <code class="literal">EXCEPTION</code> raises an error (which normally aborts the
  21     current transaction); the other levels only generate messages of different
  22     priority levels.
  23     Whether messages of a particular priority are reported to the client,
  24     written to the server log, or both is controlled by the
  25     <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
  26     <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
  27     variables. See <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a> for more
  28     information.
  29    </p><p>
  30     In the first syntax variant,
  31     after the <em class="replaceable"><code>level</code></em> if any,
  32     write a <em class="replaceable"><code>format</code></em> string
  33     (which must be a simple string literal, not an expression).  The
  34     format string specifies the error message text to be reported.
  35     The format string can be followed
  36     by optional argument expressions to be inserted into the message.
  37     Inside the format string, <code class="literal">%</code> is replaced by the
  38     string representation of the next optional argument's value. Write
  39     <code class="literal">%%</code> to emit a literal <code class="literal">%</code>.
  40     The number of arguments must match the number of <code class="literal">%</code>
  41     placeholders in the format string, or an error is raised during
  42     the compilation of the function.
  43    </p><p>
  44     In this example, the value of <code class="literal">v_job_id</code> will replace the
  45     <code class="literal">%</code> in the string:
  46 </p><pre class="programlisting">
  47 RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
  48 </pre><p>
  49    </p><p>
  50     In the second and third syntax variants,
  51     <em class="replaceable"><code>condition_name</code></em> and
  52     <em class="replaceable"><code>sqlstate</code></em> specify an
  53     error condition name or a five-character SQLSTATE code, respectively.
  54     See <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a> for the valid error condition
  55     names and the predefined SQLSTATE codes.
  56    </p><p>
  57     Here are examples
  58     of <em class="replaceable"><code>condition_name</code></em>
  59     and <em class="replaceable"><code>sqlstate</code></em> usage:
  60 </p><pre class="programlisting">
  61 RAISE division_by_zero;
  62 RAISE WARNING SQLSTATE '22012';
  63 </pre><p>
  64    </p><p>
  65     In any of these syntax variants,
  66     you can attach additional information to the error report by writing
  67     <code class="literal">USING</code> followed by <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> items.  Each
  68     <em class="replaceable"><code>expression</code></em> can be any
  69     string-valued expression.  The allowed <em class="replaceable"><code>option</code></em> key words are:
  70
  71     </p><div class="variablelist" id="RAISE-USING-OPTIONS"><dl class="variablelist"><dt id="RAISE-USING-OPTION-MESSAGE"><span class="term"><code class="literal">MESSAGE</code></span> <a href="#RAISE-USING-OPTION-MESSAGE" class="id_link">#</a></dt><dd><p>Sets the error message text.  This option can't be used in the
  72         first syntax variant, since the message is already supplied.</p></dd><dt id="RAISE-USING-OPTION-DETAIL"><span class="term"><code class="literal">DETAIL</code></span> <a href="#RAISE-USING-OPTION-DETAIL" class="id_link">#</a></dt><dd><p>Supplies an error detail message.</p></dd><dt id="RAISE-USING-OPTION-HINT"><span class="term"><code class="literal">HINT</code></span> <a href="#RAISE-USING-OPTION-HINT" class="id_link">#</a></dt><dd><p>Supplies a hint message.</p></dd><dt id="RAISE-USING-OPTION-ERRCODE"><span class="term"><code class="literal">ERRCODE</code></span> <a href="#RAISE-USING-OPTION-ERRCODE" class="id_link">#</a></dt><dd><p>Specifies the error code (SQLSTATE) to report, either by condition
  73         name, as shown in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>, or directly as a
  74         five-character SQLSTATE code.  This option can't be used in the
  75         second or third syntax variant, since the error code is already
  76         supplied.</p></dd><dt id="RAISE-USING-OPTION-COLUMN"><span class="term"><code class="literal">COLUMN</code><br /></span><span class="term"><code class="literal">CONSTRAINT</code><br /></span><span class="term"><code class="literal">DATATYPE</code><br /></span><span class="term"><code class="literal">TABLE</code><br /></span><span class="term"><code class="literal">SCHEMA</code></span> <a href="#RAISE-USING-OPTION-COLUMN" class="id_link">#</a></dt><dd><p>Supplies the name of a related object.</p></dd></dl></div><p>
  77    </p><p>
  78     This example will abort the transaction with the given error message
  79     and hint:
  80 </p><pre class="programlisting">
  81 RAISE EXCEPTION 'Nonexistent ID --&gt; %', user_id
  82       USING HINT = 'Please check your user ID';
  83 </pre><p>
  84    </p><p>
  85     These two examples show equivalent ways of setting the SQLSTATE:
  86 </p><pre class="programlisting">
  87 RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
  88 RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
  89 </pre><p>
  90     Another way to produce the same result is:
  91 </p><pre class="programlisting">
  92 RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
  93 </pre><p>
  94    </p><p>
  95     As shown in the fourth syntax variant, it is also possible to
  96     write <code class="literal">RAISE USING</code> or <code class="literal">RAISE
  97     <em class="replaceable"><code>level</code></em> USING</code> and put
  98     everything else into the <code class="literal">USING</code> list.
  99    </p><p>
 100     The last variant of <code class="command">RAISE</code> has no parameters at all.
 101     This form can only be used inside a <code class="literal">BEGIN</code> block's
 102     <code class="literal">EXCEPTION</code> clause;
 103     it causes the error currently being handled to be re-thrown.
 104    </p><div class="note"><h3 class="title">Note</h3><p>
 105      Before <span class="productname">PostgreSQL</span> 9.1, <code class="command">RAISE</code> without
 106      parameters was interpreted as re-throwing the error from the block
 107      containing the active exception handler.  Thus an <code class="literal">EXCEPTION</code>
 108      clause nested within that handler could not catch it, even if the
 109      <code class="command">RAISE</code> was within the nested <code class="literal">EXCEPTION</code> clause's
 110      block. This was deemed surprising as well as being incompatible with
 111      Oracle's PL/SQL.
 112     </p></div><p>
 113     If no condition name nor SQLSTATE is specified in a
 114     <code class="command">RAISE EXCEPTION</code> command, the default is to use
 115     <code class="literal">raise_exception</code> (<code class="literal">P0001</code>).
 116     If no message text is specified, the default is to use the condition
 117     name or SQLSTATE as message text.
 118    </p><div class="note"><h3 class="title">Note</h3><p>
 119      When specifying an error code by SQLSTATE code, you are not
 120      limited to the predefined error codes, but can select any
 121      error code consisting of five digits and/or upper-case ASCII
 122      letters, other than <code class="literal">00000</code>.  It is recommended that
 123      you avoid throwing error codes that end in three zeroes, because
 124      these are category codes and can only be trapped by trapping
 125      the whole category.
 126     </p></div></div><div class="sect2" id="PLPGSQL-STATEMENTS-ASSERT"><div class="titlepage"><div><div><h3 class="title">41.9.2. Checking Assertions <a href="#PLPGSQL-STATEMENTS-ASSERT" class="id_link">#</a></h3></div></div></div><a id="id-1.8.8.11.3.2" class="indexterm"></a><a id="id-1.8.8.11.3.3" class="indexterm"></a><a id="id-1.8.8.11.3.4" class="indexterm"></a><p>
 127     The <code class="command">ASSERT</code> statement is a convenient shorthand for
 128     inserting debugging checks into <span class="application">PL/pgSQL</span>
 129     functions.
 130
 131 </p><pre class="synopsis">
 132 ASSERT <em class="replaceable"><code>condition</code></em> [<span class="optional"> , <em class="replaceable"><code>message</code></em> </span>];
 133 </pre><p>
 134
 135     The <em class="replaceable"><code>condition</code></em> is a Boolean
 136     expression that is expected to always evaluate to true; if it does,
 137     the <code class="command">ASSERT</code> statement does nothing further.  If the
 138     result is false or null, then an <code class="literal">ASSERT_FAILURE</code> exception
 139     is raised.  (If an error occurs while evaluating
 140     the <em class="replaceable"><code>condition</code></em>, it is
 141     reported as a normal error.)
 142    </p><p>
 143     If the optional <em class="replaceable"><code>message</code></em> is
 144     provided, it is an expression whose result (if not null) replaces the
 145     default error message text <span class="quote">“<span class="quote">assertion failed</span>”</span>, should
 146     the <em class="replaceable"><code>condition</code></em> fail.
 147     The <em class="replaceable"><code>message</code></em> expression is
 148     not evaluated in the normal case where the assertion succeeds.
 149    </p><p>
 150     Testing of assertions can be enabled or disabled via the configuration
 151     parameter <code class="literal">plpgsql.check_asserts</code>, which takes a Boolean
 152     value; the default is <code class="literal">on</code>.  If this parameter
 153     is <code class="literal">off</code> then <code class="command">ASSERT</code> statements do nothing.
 154    </p><p>
 155     Note that <code class="command">ASSERT</code> is meant for detecting program
 156     bugs, not for reporting ordinary error conditions.  Use
 157     the <code class="command">RAISE</code> statement, described above, for that.
 158    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-transactions.html" title="41.8. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-trigger.html" title="41.10. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.8. Transaction Management </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"> 41.10. Trigger Functions</td></tr></table></div></body></html>