diff options
Diffstat (limited to 'doc/src/sgml/html/plpgsql-errors-and-messages.html')
| -rw-r--r-- | doc/src/sgml/html/plpgsql-errors-and-messages.html | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/src/sgml/html/plpgsql-errors-and-messages.html b/doc/src/sgml/html/plpgsql-errors-and-messages.html new file mode 100644 index 0000000..5e81650 --- /dev/null +++ b/doc/src/sgml/html/plpgsql-errors-and-messages.html @@ -0,0 +1,148 @@ +<?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>43.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="43.8. Transaction Management" /><link rel="next" href="plpgsql-trigger.html" title="43.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">43.9. Errors and Messages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-transactions.html" title="43.8. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <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 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-trigger.html" title="43.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">43.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">43.9.1. Reporting Errors and Messages</a></span></dt><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">43.9.2. Checking Assertions</a></span></dt></dl></div><div class="sect2" id="PLPGSQL-STATEMENTS-RAISE"><div class="titlepage"><div><div><h3 class="title">43.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> + Use the <code class="command">RAISE</code> statement to report messages and + raise errors. + +</p><pre class="synopsis"> +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>]; +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>]; +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>]; +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>]; +RAISE ; +</pre><p> + + The <em class="replaceable"><code>level</code></em> option specifies + the error severity. Allowed levels are <code class="literal">DEBUG</code>, + <code class="literal">LOG</code>, <code class="literal">INFO</code>, + <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>, + and <code class="literal">EXCEPTION</code>, with <code class="literal">EXCEPTION</code> + being the default. + <code class="literal">EXCEPTION</code> raises an error (which normally aborts the + current transaction); the other levels only generate messages of different + priority levels. + Whether messages of a particular priority are reported to the client, + written to the server log, or both is controlled by the + <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and + <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration + variables. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for more + information. + </p><p> + After <em class="replaceable"><code>level</code></em> if any, + you can specify a <em class="replaceable"><code>format</code></em> string + (which must be a simple string literal, not an expression). The + format string specifies the error message text to be reported. + The format string can be followed + by optional argument expressions to be inserted into the message. + Inside the format string, <code class="literal">%</code> is replaced by the + string representation of the next optional argument's value. Write + <code class="literal">%%</code> to emit a literal <code class="literal">%</code>. + The number of arguments must match the number of <code class="literal">%</code> + placeholders in the format string, or an error is raised during + the compilation of the function. + </p><p> + In this example, the value of <code class="literal">v_job_id</code> will replace the + <code class="literal">%</code> in the string: +</p><pre class="programlisting"> +RAISE NOTICE 'Calling cs_create_job(%)', v_job_id; +</pre><p> + </p><p> + You can attach additional information to the error report by writing + <code class="literal">USING</code> followed by <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> items. Each + <em class="replaceable"><code>expression</code></em> can be any + string-valued expression. The allowed <em class="replaceable"><code>option</code></em> key words are: + + </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 + form of <code class="command">RAISE</code> that includes a format string + before <code class="literal">USING</code>.</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 + name, as shown in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>, or directly as a + five-character SQLSTATE code.</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> + </p><p> + This example will abort the transaction with the given error message + and hint: +</p><pre class="programlisting"> +RAISE EXCEPTION 'Nonexistent ID --> %', user_id + USING HINT = 'Please check your user ID'; +</pre><p> + </p><p> + These two examples show equivalent ways of setting the SQLSTATE: +</p><pre class="programlisting"> +RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation'; +RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505'; +</pre><p> + </p><p> + There is a second <code class="command">RAISE</code> syntax in which the main argument + is the condition name or SQLSTATE to be reported, for example: +</p><pre class="programlisting"> +RAISE division_by_zero; +RAISE SQLSTATE '22012'; +</pre><p> + In this syntax, <code class="literal">USING</code> can be used to supply a custom + error message, detail, or hint. Another way to do the earlier + example is +</p><pre class="programlisting"> +RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id; +</pre><p> + </p><p> + Still another variant is to write <code class="literal">RAISE USING</code> or <code class="literal">RAISE + <em class="replaceable"><code>level</code></em> USING</code> and put + everything else into the <code class="literal">USING</code> list. + </p><p> + The last variant of <code class="command">RAISE</code> has no parameters at all. + This form can only be used inside a <code class="literal">BEGIN</code> block's + <code class="literal">EXCEPTION</code> clause; + it causes the error currently being handled to be re-thrown. + </p><div class="note"><h3 class="title">Note</h3><p> + Before <span class="productname">PostgreSQL</span> 9.1, <code class="command">RAISE</code> without + parameters was interpreted as re-throwing the error from the block + containing the active exception handler. Thus an <code class="literal">EXCEPTION</code> + clause nested within that handler could not catch it, even if the + <code class="command">RAISE</code> was within the nested <code class="literal">EXCEPTION</code> clause's + block. This was deemed surprising as well as being incompatible with + Oracle's PL/SQL. + </p></div><p> + If no condition name nor SQLSTATE is specified in a + <code class="command">RAISE EXCEPTION</code> command, the default is to use + <code class="literal">raise_exception</code> (<code class="literal">P0001</code>). + If no message text is specified, the default is to use the condition + name or SQLSTATE as message text. + </p><div class="note"><h3 class="title">Note</h3><p> + When specifying an error code by SQLSTATE code, you are not + limited to the predefined error codes, but can select any + error code consisting of five digits and/or upper-case ASCII + letters, other than <code class="literal">00000</code>. It is recommended that + you avoid throwing error codes that end in three zeroes, because + these are category codes and can only be trapped by trapping + the whole category. + </p></div></div><div class="sect2" id="PLPGSQL-STATEMENTS-ASSERT"><div class="titlepage"><div><div><h3 class="title">43.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> + The <code class="command">ASSERT</code> statement is a convenient shorthand for + inserting debugging checks into <span class="application">PL/pgSQL</span> + functions. + +</p><pre class="synopsis"> +ASSERT <em class="replaceable"><code>condition</code></em> [<span class="optional"> , <em class="replaceable"><code>message</code></em> </span>]; +</pre><p> + + The <em class="replaceable"><code>condition</code></em> is a Boolean + expression that is expected to always evaluate to true; if it does, + the <code class="command">ASSERT</code> statement does nothing further. If the + result is false or null, then an <code class="literal">ASSERT_FAILURE</code> exception + is raised. (If an error occurs while evaluating + the <em class="replaceable"><code>condition</code></em>, it is + reported as a normal error.) + </p><p> + If the optional <em class="replaceable"><code>message</code></em> is + provided, it is an expression whose result (if not null) replaces the + default error message text <span class="quote">“<span class="quote">assertion failed</span>”</span>, should + the <em class="replaceable"><code>condition</code></em> fail. + The <em class="replaceable"><code>message</code></em> expression is + not evaluated in the normal case where the assertion succeeds. + </p><p> + Testing of assertions can be enabled or disabled via the configuration + parameter <code class="literal">plpgsql.check_asserts</code>, which takes a Boolean + value; the default is <code class="literal">on</code>. If this parameter + is <code class="literal">off</code> then <code class="command">ASSERT</code> statements do nothing. + </p><p> + Note that <code class="command">ASSERT</code> is meant for detecting program + bugs, not for reporting ordinary error conditions. Use + the <code class="command">RAISE</code> statement, described above, for that. + </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="43.8. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-trigger.html" title="43.10. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.8. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.10. Trigger Functions</td></tr></table></div></body></html>
\ No newline at end of file |