mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: improve description of plpgsql's RAISE command.

Browse Source 
RAISE accepts either = or := in the USING clause, so fix the
syntax synopsis to show that.

Rearrange and wordsmith the descriptions of the different syntax
variants, in hopes of improving clarity.

Igor Gnatyuk, reviewed by Jian He and Laurenz Albe; minor additional
wordsmithing by me

Discussion: https://postgr.es/m/CAEu6iLvhF5sdGeat2x4_L0FvWW_SiN--ma8ya7CZd-oJoV+yqQ@mail.gmail.com
This commit is contained in:
Tom Lane 2024-07-18 12:37:51 -04:00
parent 402b586d0a
commit 56c6be57af
1 changed files with 35 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
doc/src/sgml/plpgsql.sgml
View File

@ -3815,10 +3815,10 @@ CALL transaction_test2();
raise errors.
<synopsis>
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ... </optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> <replaceable class="parameter">condition_name</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> SQLSTATE '<replaceable class="parameter">sqlstate</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">level</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> { = | := } <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>
@ -3840,8 +3840,9 @@ RAISE ;
</para>
<para>
After <replaceable class="parameter">level</replaceable> if any,
you can specify a <replaceable class="parameter">format</replaceable> string
In the first syntax variant,
after the <replaceable class="parameter">level</replaceable> if any,
write a <replaceable class="parameter">format</replaceable> 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
@ -3863,7 +3864,27 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
</para>
<para>
You can attach additional information to the error report by writing
In the second and third syntax variants,
<replaceable class="parameter">condition_name</replaceable> and
<replaceable class="parameter">sqlstate</replaceable> specify an
error condition name or a five-character SQLSTATE code, respectively.
See <xref linkend="errcodes-appendix"/> for the valid error condition
names and the predefined SQLSTATE codes.
</para>
<para>
Here are examples
of <replaceable class="parameter">condition_name</replaceable>
and <replaceable class="parameter">sqlstate</replaceable> usage:
<programlisting>
RAISE division_by_zero;
RAISE WARNING SQLSTATE '22012';
</programlisting>
</para>
<para>
In any of these syntax variants,
you can attach additional information to the error report by writing
<literal>USING</literal> followed by <replaceable
class="parameter">option</replaceable> = <replaceable
class="parameter">expression</replaceable> items. Each
@ -3876,8 +3897,7 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
<term><literal>MESSAGE</literal></term>
<listitem>
<para>Sets the error message text. This option can't be used in the
form of <command>RAISE</command> that includes a format string
before <literal>USING</literal>.</para>
first syntax variant, since the message is already supplied.</para>
</listitem>
</varlistentry>
@ -3900,7 +3920,9 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
<listitem>
<para>Specifies the error code (SQLSTATE) to report, either by condition
name, as shown in <xref linkend="errcodes-appendix"/>, or directly as a
five-character SQLSTATE code.</para>
five-character SQLSTATE code. This option can't be used in the
second or third syntax variant, since the error code is already
supplied.</para>
</listitem>
</varlistentry>
@ -3932,25 +3954,15 @@ RAISE EXCEPTION 'Nonexistent ID --> %', user_id
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</programlisting>
</para>
<para>
There is a second <command>RAISE</command> syntax in which the main argument
is the condition name or SQLSTATE to be reported, for example:
<programlisting>
RAISE division_by_zero;
RAISE SQLSTATE '22012';
</programlisting>
In this syntax, <literal>USING</literal> can be used to supply a custom
error message, detail, or hint. Another way to do the earlier
example is
Another way to produce the same result is:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
</para>
<para>
Still another variant is to write <literal>RAISE USING</literal> or <literal>RAISE
As shown in the fourth syntax variant, it is also possible to
write <literal>RAISE USING</literal> or <literal>RAISE
<replaceable class="parameter">level</replaceable> USING</literal> and put
everything else into the <literal>USING</literal> list.
</para>