From 56c6be57af6bd1c7eb7dff50e5f169ced4ed3045 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 18 Jul 2024 12:37:51 -0400 Subject: [PATCH] Doc: improve description of plpgsql's RAISE command. 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 --- doc/src/sgml/plpgsql.sgml | 58 +++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 071f5a87d3..9b1977022a 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -3815,10 +3815,10 @@ CALL transaction_test2(); raise errors. -RAISE level 'format' , expression , ... USING option = expression , ... ; -RAISE level condition_name USING option = expression , ... ; -RAISE level SQLSTATE 'sqlstate' USING option = expression , ... ; -RAISE level USING option = expression , ... ; +RAISE level 'format' , expression , ... USING option { = | := } expression , ... ; +RAISE level condition_name USING option { = | := } expression , ... ; +RAISE level SQLSTATE 'sqlstate' USING option { = | := } expression , ... ; +RAISE level USING option { = | := } expression , ... ; RAISE ; @@ -3840,8 +3840,9 @@ RAISE ; - After level if any, - you can specify a format string + In the first syntax variant, + after the level if any, + write a format 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; - You can attach additional information to the error report by writing + In the second and third syntax variants, + condition_name and + sqlstate specify an + error condition name or a five-character SQLSTATE code, respectively. + See for the valid error condition + names and the predefined SQLSTATE codes. + + + + Here are examples + of condition_name + and sqlstate usage: + +RAISE division_by_zero; +RAISE WARNING SQLSTATE '22012'; + + + + + In any of these syntax variants, + you can attach additional information to the error report by writing USING followed by option = expression items. Each @@ -3876,8 +3897,7 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id; MESSAGE Sets the error message text. This option can't be used in the - form of RAISE that includes a format string - before USING. + first syntax variant, since the message is already supplied. @@ -3900,7 +3920,9 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id; Specifies the error code (SQLSTATE) to report, either by condition name, as shown in , or directly as a - five-character SQLSTATE code. + five-character SQLSTATE code. This option can't be used in the + second or third syntax variant, since the error code is already + supplied. @@ -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'; - - - - There is a second RAISE syntax in which the main argument - is the condition name or SQLSTATE to be reported, for example: - -RAISE division_by_zero; -RAISE SQLSTATE '22012'; - - In this syntax, USING 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: RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id; - Still another variant is to write RAISE USING or RAISE + As shown in the fourth syntax variant, it is also possible to + write RAISE USING or RAISE level USING and put everything else into the USING list.