agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feed[PATCH] No more virgins
9+ messages / 6 participants
[nested] [flat]
* [PATCH] No more virgins
@ 2019-11-08 13:09 Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 9+ messages in thread
From: Alvaro Herrera @ 2019-11-08 13:09 UTC (permalink / raw)
---
doc/src/sgml/manage-ag.sgml | 5 +++--
doc/src/sgml/ref/create_database.sgml | 2 +-
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 0154064e50..a939ce8313 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -199,11 +199,12 @@ createdb -O <replaceable>rolename</replaceable> <replaceable>dbname</replaceable
should never be changed after the database cluster has been
initialized. By instructing
<command>CREATE DATABASE</command> to copy <literal>template0</literal> instead
- of <literal>template1</literal>, you can create a <quote>virgin</quote> user
+ of <literal>template1</literal>, you can create a user
database that contains none of the site-local additions in
<literal>template1</literal>. This is particularly handy when restoring a
<literal>pg_dump</literal> dump: the dump script should be restored in a
- virgin database to ensure that one recreates the correct contents
+ database without any user-defined objects, to ensure that one recreates
+ the correct contents
of the dumped database, without conflicting with objects that
might have been added to <literal>template1</literal> later on.
</para>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 4014f6703b..e56aca6d30 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -54,7 +54,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
system database <literal>template1</literal>. A different template can be
specified by writing <literal>TEMPLATE
<replaceable class="parameter">name</replaceable></literal>. In particular,
- by writing <literal>TEMPLATE template0</literal>, you can create a virgin
+ by writing <literal>TEMPLATE template0</literal>, you can create a
database containing only the standard objects predefined by your
version of <productname>PostgreSQL</productname>. This is useful
if you wish to avoid copying
--
2.20.1
--IS0zKkzwUGydFO0o--
^ permalink raw reply [nested|flat] 9+ messages in thread
* Undocumented optionality of handler_statements
@ 2024-07-22 13:55 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 9+ messages in thread
From: PG Doc comments form @ 2024-07-22 13:55 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: philipp.salvisberg@gmail.com
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.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-07-22 23:39 Michael Paquier <michael@paquier.xyz>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 9+ messages in thread
From: Michael Paquier @ 2024-07-22 23:39 UTC (permalink / raw)
To: philipp.salvisberg@gmail.com; pgsql-docs@lists.postgresql.org
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
Attachments:
[application/pgp-signature] signature.asc (832B, ../../Zp7tqLSTbBaBTUlP@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-07-23 11:25 Philipp Salvisberg <philipp.salvisberg@gmail.com>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 9+ messages in thread
From: Philipp Salvisberg @ 2024-07-23 11:25 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-docs@lists.postgresql.org
> 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:
[application/octet-stream] doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff (1.0K, ../../D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com/3-doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff)
download | inline diff:
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 -- <co id="co.plpgsql-porting-exception"/>
- -- don't worry if it already exists
+ NULL; -- don't worry if it already exists
END;
COMMIT;
END;
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-09-11 06:37 Michael Paquier <michael@paquier.xyz>
parent: Philipp Salvisberg <philipp.salvisberg@gmail.com>
0 siblings, 2 replies; 9+ messages in thread
From: Michael Paquier @ 2024-09-11 06:37 UTC (permalink / raw)
To: Philipp Salvisberg <philipp.salvisberg@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
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:
[text/x-diff] doc-plpgsql-error.patch (1.5K, ../../ZuE6ndanu0Z_9NWM@paquier.xyz/2-doc-plpgsql-error.patch)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 78e4983139..3a5e7bc296 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2804,9 +2804,9 @@ BEGIN
<replaceable>statements</replaceable>
EXCEPTION
WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
- <replaceable>handler_statements</replaceable>
+ <optional> <replaceable>handler_statements</replaceable> </optional>
<optional> WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
- <replaceable>handler_statements</replaceable>
+ <optional> <replaceable>handler_statements</replaceable> </optional>
... </optional>
END;
</synopsis>
@@ -2821,8 +2821,8 @@ END;
abandoned, and control passes to the <literal>EXCEPTION</literal> list.
The list is searched for the first <replaceable>condition</replaceable>
matching the error that occurred. If a match is found, the
- corresponding <replaceable>handler_statements</replaceable> are
- executed, and then control passes to the next statement after
+ corresponding <replaceable>handler_statements</replaceable>, if
+ specified are executed, and then control passes to the next statement after
<literal>END</literal>. If no match is found, the error propagates out
as though the <literal>EXCEPTION</literal> clause were not there at all:
the error can be caught by an enclosing block with
[application/pgp-signature] signature.asc (832B, ../../ZuE6ndanu0Z_9NWM@paquier.xyz/3-signature.asc)
download
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-09-13 15:28 Philipp Salvisberg <philipp.salvisberg@gmail.com>
parent: Michael Paquier <michael@paquier.xyz>
1 sibling, 1 reply; 9+ messages in thread
From: Philipp Salvisberg @ 2024-09-13 15:28 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-docs@lists.postgresql.org
>> 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.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-09-13 15:56 David G. Johnston <david.g.johnston@gmail.com>
parent: Philipp Salvisberg <philipp.salvisberg@gmail.com>
0 siblings, 0 replies; 9+ messages in thread
From: David G. Johnston @ 2024-09-13 15:56 UTC (permalink / raw)
To: Philipp Salvisberg <philipp.salvisberg@gmail.com>; +Cc: Michael Paquier <michael@paquier.xyz>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-10-16 22:11 Bruce Momjian <bruce@momjian.us>
parent: Michael Paquier <michael@paquier.xyz>
1 sibling, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2024-10-16 22:11 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: Philipp Salvisberg <philipp.salvisberg@gmail.com>; pgsql-docs@lists.postgresql.org
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:
[text/x-diff] doc-plpgsql-error.patch (1.5K, ../../ZxA6JgzZ9vh_KWWr@momjian.us/2-doc-plpgsql-error.patch)
download | inline diff:
iff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 78e4983139..3a5e7bc296 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2804,9 +2804,9 @@ BEGIN
<replaceable>statements</replaceable>
EXCEPTION
WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
- <replaceable>handler_statements</replaceable>
+ <optional> <replaceable>handler_statements</replaceable> </optional>
<optional> WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
- <replaceable>handler_statements</replaceable>
+ <optional> <replaceable>handler_statements</replaceable> </optional>
... </optional>
END;
</synopsis>
@@ -2821,8 +2821,8 @@ END;
abandoned, and control passes to the <literal>EXCEPTION</literal> list.
The list is searched for the first <replaceable>condition</replaceable>
matching the error that occurred. If a match is found, the
- corresponding <replaceable>handler_statements</replaceable> are
- executed, and then control passes to the next statement after
+ corresponding <replaceable>handler_statements</replaceable>, if
+ specified, are executed, and then control passes to the next statement after
<literal>END</literal>. If no match is found, the error propagates out
as though the <literal>EXCEPTION</literal> clause were not there at all:
the error can be caught by an enclosing block with
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Undocumented optionality of handler_statements
@ 2024-10-16 22:45 David G. Johnston <david.g.johnston@gmail.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 9+ messages in thread
From: David G. Johnston @ 2024-10-16 22:45 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Michael Paquier <michael@paquier.xyz>; Philipp Salvisberg <philipp.salvisberg@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2024-10-16 22:45 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-11-08 13:09 [PATCH] No more virgins Alvaro Herrera <alvherre@alvh.no-ip.org>
2024-07-22 13:55 Undocumented optionality of handler_statements PG Doc comments form <noreply@postgresql.org>
2024-07-22 23:39 ` Re: Undocumented optionality of handler_statements Michael Paquier <michael@paquier.xyz>
2024-07-23 11:25 ` Re: Undocumented optionality of handler_statements Philipp Salvisberg <philipp.salvisberg@gmail.com>
2024-09-11 06:37 ` Re: Undocumented optionality of handler_statements Michael Paquier <michael@paquier.xyz>
2024-09-13 15:28 ` Re: Undocumented optionality of handler_statements Philipp Salvisberg <philipp.salvisberg@gmail.com>
2024-09-13 15:56 ` Re: Undocumented optionality of handler_statements David G. Johnston <david.g.johnston@gmail.com>
2024-10-16 22:11 ` Re: Undocumented optionality of handler_statements Bruce Momjian <bruce@momjian.us>
2024-10-16 22:45 ` Re: Undocumented optionality of handler_statements David G. Johnston <david.g.johnston@gmail.com>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox