Thread: Undocumented optionality of handler_statements

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/plpgsql-control-structures.html
Description:

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.


drop table if exists t;
create table t (id integer not null primary key);
do $$
begin
    insert into t (id) values (1), (1);
exception when unique_violation then
    -- ignore without calling null statement
end
$$;

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.

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

>> 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).
> 
> These examples have been around for 20 years with, and I think that it
> is helpful to show this pattern as well.  So if I were to do something
> about that, I would suggest the attached.

I agree. Expressing the optionality in the synopsis/EBNF is the
better way. Therefore I suggest adding the optionality also for the 
"statements" in this section (43.6.8. Trapping Errors). And of course,
the optionality should be added for all related "statements" in other
sections such as 

- 43.2. Structure of PL/pgSQL
- 43.6.4.1. IF-THEN 
- 43.6.4.2. IF-THEN-ELSE
- 43.6.4.3. IF-THEN-ELSIF
- 43.6.4.4. Simple CASE
- 43.6.4.5. Searched CASE 
- 43.6.5.1. LOOP
- 43.6.5.4. WHILE
- 43.6.5.5. FOR (Integer Variant)
- 43.6.6. Looping through Query Results
- 43.6.7. Looping through Arrays
- 43.7.4. Looping through a Cursor's Result

The PL/pgSQL implementation allows empty branches.

>> 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).
>
> These examples have been around for 20 years with, and I think that it
> is helpful to show this pattern as well.  So if I were to do something
> about that, I would suggest the attached.

I agree. Expressing the optionality in the synopsis/EBNF is the
better way. Therefore I suggest adding the optionality also for the
"statements" in this section (43.6.8. Trapping Errors). And of course,
the optionality should be added for all related "statements" in other
sections such as 

On Wed, Sep 11, 2024 at 03:37:17PM +0900, Michael Paquier wrote:
> On Tue, Jul 23, 2024 at 01:25:39PM +0200, Philipp Salvisberg wrote:
> > read "optional" as "mandatory".
>
> They're optional, like in empty being optional.  If not specified, the
> block goes to its END.
>
> > 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).
>
> These examples have been around for 20 years with, and I think that it
> is helpful to show this pattern as well.  So if I were to do something
> about that, I would suggest the attached.

Do we want to apply this patch?  I added a comma to the text, attached.