Re: Undocumented optionality of handler_statements

> On 23 Jul 2024, at 01:39, Michael Paquier <michael(at)paquier(dot)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