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
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:
doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diffapplication/octet-stream; name=doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff; x-unix-mode=0644Download+3-3
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.
--
Michael
Attachments:
doc-plpgsql-error.patchtext/x-diff; charset=us-asciiDownload+4-4
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.
On Friday, September 13, 2024, Philipp Salvisberg <
philipp.salvisberg@gmail.com> wrote:
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
This concept is already covered by:
https://www.postgresql.org/docs/16/plpgsql-statements.html#PLPGSQL-STATEMENTS-NULL
These placeholders indicate where a set of statements goes. That set is
not optional. The set can be empty - as documented at the link above -
though IMO it is better to encourage representing the empty set as the
one-element set with the NULL no-op statement. I would make all our
examples use NULL and the reader, if finding an example of an empty-set in
the wild, can be pointed to the above section for confirmation that it is
not a bug.
David J.
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.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"
Attachments:
doc-plpgsql-error.patchtext/x-diff; charset=us-asciiDownload+4-4
On Wednesday, October 16, 2024, Bruce Momjian <bruce@momjian.us> wrote:
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.
-1 for me.
This establishes a policy change for documenting an empty set of statements
without touching all places that would require changing to conform to the
new policy.
I’m weakly against changing the policy at this point; if we do the patch
needs to touch all relevant places.
David J.