agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Philipp Salvisberg <philipp.salvisberg@gmail.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented optionality of handler_statements
Date: Tue, 23 Jul 2024 13:25:39 +0200
Message-ID: <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com> (raw)
In-Reply-To: <Zp7tqLSTbBaBTUlP@paquier.xyz>
References: <172165655256.710.2097726158572647813@wrigleys.postgresql.org>
<Zp7tqLSTbBaBTUlP@paquier.xyz>
> On 23 Jul 2024, at 01:39, Michael Paquier <michael@paquier.xyz> wrote:
>
> On Mon, Jul 22, 2024 at 01:55:52PM +0000, PG Doc comments form wrote:
>> In
>> https://www.postgresql.org/docs/16/plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING
>> handler_statements are documented as optional.
>>
>> However, the following example shows that handler_statements can be omitted.
>
> You have a good point. This could be clarified better in the
> documentation by making handler_statements conditional with square
> brackets around it. I'd rather add an extra sentence to tell that not
> specifying handler_statements is equivalent to taking no action.
>
> Perhaps you would like to write a patch?
> --
> Michael
First of all I'd like to correct a statement made in the initial post
> In
> https://www.postgresql.org/docs/16/plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING
> handler_statements are documented as optional.
read "optional" as "mandatory".
The question is whether we want to treat that as an implementation detail or not. In other words, whether we want to document it. I'm fairly new to PostgreSQL and have no idea how you handle such things. However, I would treat the optionality in this case as an implementation detail. Why? To be consistent with other series of PL/pgSQL statements in PL/pgSQL blocks, IF statements, CASE statements, loops, etc. Also, I think that writing an empty exception handler is not something to recommend and would not advocate it in the documentation.
In my initial post I wrote
> I stumbled over it when running the example documented in
> https://www.postgresql.org/docs/current/plpgsql-trigger.html#PLPGSQL-TRIGGER-SUMMARY-EXAMPLE
> - it also contains an exception handler without handler statements.
Therefore, I suggest to change this example by adding a NULL statement as in other examples. This change would make the documentation consistent and handle the optionality of handler_statements as an implementation detail. I created a patch for plpgsql.sgml based on the master branch, adding a NULL statement in empty exception handlers (see attached file doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff).
I hope this is acceptable.
Thanks, Philipp
=
Attachments:
[application/octet-stream] doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff (1.0K, ../D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com/3-doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index a675923867..79664eee47 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2921,7 +2921,7 @@ BEGIN
INSERT INTO db(a,b) VALUES (key, data);
RETURN;
EXCEPTION WHEN unique_violation THEN
- -- Do nothing, and loop to try the UPDATE again.
+ NULL; -- Do nothing, and loop to try the UPDATE again.
END;
END LOOP;
END;
@@ -4619,7 +4619,7 @@ AS $maint_sales_summary_bytime$
EXCEPTION
WHEN UNIQUE_VIOLATION THEN
- -- do nothing
+ NULL; -- do nothing
END;
END LOOP insert_update;
@@ -5923,7 +5923,7 @@ BEGIN
INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
EXCEPTION
WHEN unique_violation THEN -- <co id="co.plpgsql-porting-exception"/>
- -- don't worry if it already exists
+ NULL; -- don't worry if it already exists
END;
COMMIT;
END;
view thread (9+ messages) latest in thread
Message-ID: <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
Permalink: ../D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com/
Also on: postgresql.org/message-id/D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: philipp.salvisberg@gmail.com, michael@paquier.xyz, pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented optionality of handler_statements
In-Reply-To: <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox