Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1sWDeO-00Dt74-AR for pgsql-docs@arkaria.postgresql.org; Tue, 23 Jul 2024 11:25:48 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1sWDeM-00CiZV-F2 for pgsql-docs@arkaria.postgresql.org; Tue, 23 Jul 2024 11:25:46 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1sWDeM-00CiZM-4u for pgsql-docs@lists.postgresql.org; Tue, 23 Jul 2024 11:25:46 +0000 Received: from mail-lj1-x234.google.com ([2a00:1450:4864:20::234]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.94.2) (envelope-from ) id 1sWDeJ-001302-Lq for pgsql-docs@lists.postgresql.org; Tue, 23 Jul 2024 11:25:45 +0000 Received: by mail-lj1-x234.google.com with SMTP id 38308e7fff4ca-2ebe40673e8so66778061fa.3 for ; Tue, 23 Jul 2024 04:25:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1721733943; x=1722338743; darn=lists.postgresql.org; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:from:to:cc:subject:date:message-id:reply-to; bh=jPIi7GXTmOIv16+ZdqrXbJjEB1DCFQ/DQJRmZJ4PYpQ=; b=eyT4fAiX5wFKUtKsfPjfVvtD1dOJcR+YFiVD9uKdWYsCQtRyvd6ue+hF2jSsRhnWMJ hNa/Qfx80pZKlOh7vdAGJKnGWTxc4uE0ke3yt4CHaJxV26otvMD7x4EUkn1cv+AffZGr ssvyY4eTEjkKJTawa023AWpx6Amkxf0aB+07szmKZEPGMqpVQsoWYvt/veBHJbxyEeoV NDpxq9ZiBaDlnJoi0JPwnPtB37pZ+aSgV3eoH9M78p42ZErnpyJzXE0uXZEySg2lB5/b /dmdtd9Ksa1h2xMcqWQYlgayoqLMiynqGAvwJVNitsDKaLVakDye4rbF2/NT04dEZf/1 S4hg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721733943; x=1722338743; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=jPIi7GXTmOIv16+ZdqrXbJjEB1DCFQ/DQJRmZJ4PYpQ=; b=bsdx7PZEeuwtxGM/+ZKom53h0DT0LyirW/27x/oY97iFzlNlkj/xd1napaW2vkDadM h9JHa80WSFM1WzWN1znNOk9v72kjBfqY3yz9cG5N+UKMxNTXy6m1WTnrANEj9AWthNOt DVmgyPU4uL2JUqwOYbsd8mf7Ts8+gMmCGVUYe6JmFLWZn2dYfB05+ahLeir2VUiutrcA dwMFbwWVvsw/ULPfPylHzBnBH9t/+9LSeXabwrjjHrMVguzoORfhACwCLuq6yYj4Sp/i TS+noTMQ8EAq/54MRHooRvj7nXMCaNt0XiqLjBDcuGfcwXKezRdR6fJYaDvmH0UsbbFH ZiHA== X-Gm-Message-State: AOJu0YxT0mOcpAxcopBc0XbedDKJapRcDDl4DRmH9Wy6wDj9L7V0oU7L Mqw0XZjrXy34PofrBjNpk8l3L5gUBRS/IIAVm7+170nb/6i0cWwlsLZHvR7o X-Google-Smtp-Source: AGHT+IFhkHaN1R0hm7/tGGv/sTgzlHVRchtWpdxG4wCpAfPPUJv2wVYsXPWo/biMutLWB6uxN87xug== X-Received: by 2002:a2e:8709:0:b0:2ef:32b9:85f6 with SMTP id 38308e7fff4ca-2ef32b98f02mr32186111fa.11.1721733942145; Tue, 23 Jul 2024 04:25:42 -0700 (PDT) Received: from smtpclient.apple ([2a02:121f:3ed6:0:88e1:e01f:2401:d7a6]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5a30c9be31fsm7335235a12.92.2024.07.23.04.25.40 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 23 Jul 2024 04:25:40 -0700 (PDT) From: Philipp Salvisberg Message-Id: Content-Type: multipart/alternative; boundary="Apple-Mail=_D5441030-B492-4162-889E-B33F9F9E176E" Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3774.600.62\)) Subject: Re: Undocumented optionality of handler_statements Date: Tue, 23 Jul 2024 13:25:39 +0200 In-Reply-To: Cc: pgsql-docs@lists.postgresql.org To: Michael Paquier References: <172165655256.710.2097726158572647813@wrigleys.postgresql.org> X-Mailer: Apple Mail (2.3774.600.62) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --Apple-Mail=_D5441030-B492-4162-889E-B33F9F9E176E Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On 23 Jul 2024, at 01:39, Michael Paquier wrote: >=20 > 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. >>=20 >> However, the following example shows that handler_statements can be = omitted. >=20 > 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. >=20 > 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.=20 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-TRIGG= ER-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 =EF=BF=BC= --Apple-Mail=_D5441030-B492-4162-889E-B33F9F9E176E Content-Type: multipart/mixed; boundary="Apple-Mail=_D5EE94E8-71BD-47BF-A036-B01AC0189A94" --Apple-Mail=_D5EE94E8-71BD-47BF-A036-B01AC0189A94 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=us-ascii


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-str= uctures.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


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#PLPGSQ= L-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

= --Apple-Mail=_D5EE94E8-71BD-47BF-A036-B01AC0189A94 Content-Disposition: attachment; filename*0=doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.; filename*1=diff Content-Type: application/octet-stream; x-unix-mode=0644; name="doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff" Content-Transfer-Encoding: 7bit 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 -- - -- don't worry if it already exists + NULL; -- don't worry if it already exists END; COMMIT; END; --Apple-Mail=_D5EE94E8-71BD-47BF-A036-B01AC0189A94 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii --Apple-Mail=_D5EE94E8-71BD-47BF-A036-B01AC0189A94-- --Apple-Mail=_D5441030-B492-4162-889E-B33F9F9E176E--