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