Thread
-
Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-09-24T22:57:47Z
Hi, I have made various, mostly unrelated to each other, small improvements to the documentation. These are usually in the areas of plpgsql, schemas, and permissions. Most change 1 lines, but some supply short overviews. "Short" is subjective, so if these need to be broken into different threads or different commitfest entries let me know. I'm starting simple and submitting a single patch. Attached: various_doc_patches_v1.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Daniel Gustafsson <daniel@yesql.se> — 2023-09-25T07:26:38Z
> On 25 Sep 2023, at 00:57, Karl O. Pinc <kop@karlpinc.com> wrote: > I have made various, mostly unrelated to each other, > small improvements to the documentation. These > are usually in the areas of plpgsql, schemas, and permissions. > Most change 1 lines, but some supply short overviews. > > "Short" is subjective, so if these need to be > broken into different threads or different > commitfest entries let me know. While I agree it's subjective, I don't think adding a new section or paragraph qualifies as short or small. I would prefer if each (related) change is in a single commit with a commit message which describes the motivation for the change. A reviewer can second-guess the rationale for the changes, but they shouldn't have to. The resulting patchset can all be in the same thread though. -- Daniel Gustafsson
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-09-25T12:00:49Z
On Mon, 25 Sep 2023 09:26:38 +0200 Daniel Gustafsson <daniel@yesql.se> wrote: > > On 25 Sep 2023, at 00:57, Karl O. Pinc <kop@karlpinc.com> wrote: > > > I have made various, mostly unrelated to each other, > > small improvements to the documentation. > While I agree it's subjective, I don't think adding a new section or > paragraph qualifies as short or small. I would prefer if each > (related) change is in a single commit with a commit message which > describes the motivation for the change. A reviewer can second-guess > the rationale for the changes, but they shouldn't have to. Will do. Is there a preferred data format or should I send each patch in a separate attachment with description? > The resulting patchset can all be in the same thread though. Thanks. Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Daniel Gustafsson <daniel@yesql.se> — 2023-09-25T12:14:37Z
> On 25 Sep 2023, at 14:00, Karl O. Pinc <kop@karlpinc.com> wrote: > Is there a preferred data format or should I send > each patch in a separate attachment with description? The easiest way would be to create a patchset off of master I think. In a branch, commit each change with an explanatory commit message. Once done you can do "git format-patch origin/master -v 1" which will generate a set of n patches named v1-0001 through v1-000n. You can then attache those to the thread. This will make it easier for a reviewer, and it's easy to apply them in the right order in case one change depends on another earlier change. -- Daniel Gustafsson
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-09-25T22:55:59Z
On Mon, 25 Sep 2023 14:14:37 +0200 Daniel Gustafsson <daniel@yesql.se> wrote: > > On 25 Sep 2023, at 14:00, Karl O. Pinc <kop@karlpinc.com> wrote: > > > Is there a preferred data format or should I send > > each patch in a separate attachment with description? > Once done you can do "git format-patch origin/master -v 1" which will > generate a set of n patches named v1-0001 through v1-000n. You can > then attache those to the thread. Done. 11 patches attached. Thanks for the help. (This is v2, since I made some changes upon review.) I am not particularly confident in the top-line commit descriptions. Some seem kind of long and not a whole lot of thought went into them. But the commit descriptions are for the committer to decide anyway. The bulk of the commit descriptions are very wordy and will surely need at least some editing. Listing all the attachments here for future discussion: v2-0001-Change-section-heading-to-better-reflect-saving-a.patch v2-0002-Change-section-heading-to-better-describe-referen.patch v2-0003-Better-section-heading-for-plpgsql-exception-trap.patch v2-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v2-0005-Improve-sentences-in-overview-of-system-configura.patch v2-0006-Provide-examples-of-listing-all-settings.patch v2-0007-Cleanup-summary-of-role-powers.patch v2-0008-Explain-the-difference-between-role-attributes-an.patch v2-0009-Document-the-oidvector-type.patch v2-0010-Improve-sentences-about-the-significance-of-the-s.patch v2-0011-Add-a-sub-section-to-describe-schema-resolution.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-09-26T04:30:38Z
Version 3. Re-do title, which is all of patch v3-003. On Mon, 25 Sep 2023 17:55:59 -0500 "Karl O. Pinc" <kop@karlpinc.com> wrote: > On Mon, 25 Sep 2023 14:14:37 +0200 > Daniel Gustafsson <daniel@yesql.se> wrote: > > Once done you can do "git format-patch origin/master -v 1" which > > will generate a set of n patches named v1-0001 through v1-000n. > Done. 11 patches attached. Thanks for the help. > I am not particularly confident in the top-line commit > descriptions. > The bulk of the commit descriptions are very wordy > Listing all the attachments here for future discussion: v3-0001-Change-section-heading-to-better-reflect-saving-a.patch v3-0002-Change-section-heading-to-better-describe-referen.patch v3-0003-Better-section-heading-for-plpgsql-exception-trap.patch v3-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v3-0005-Improve-sentences-in-overview-of-system-configura.patch v3-0006-Provide-examples-of-listing-all-settings.patch v3-0007-Cleanup-summary-of-role-powers.patch v3-0008-Explain-the-difference-between-role-attributes-an.patch v3-0009-Document-the-oidvector-type.patch v3-0010-Improve-sentences-about-the-significance-of-the-s.patch v3-0011-Add-a-sub-section-to-describe-schema-resolution.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-09-26T04:37:44Z
Forgot to attach. Sorry. On Mon, 25 Sep 2023 23:30:38 -0500 "Karl O. Pinc" <kop@karlpinc.com> wrote: > Version 3. > > Re-do title, which is all of patch v3-003. > > On Mon, 25 Sep 2023 17:55:59 -0500 > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > Once done you can do "git format-patch origin/master -v 1" which > > > will generate a set of n patches named v1-0001 through v1-000n. > > > Done. 11 patches attached. Thanks for the help. > > > I am not particularly confident in the top-line commit > > descriptions. > > > The bulk of the commit descriptions are very wordy > > > Listing all the attachments here for future discussion: > > v3-0001-Change-section-heading-to-better-reflect-saving-a.patch > v3-0002-Change-section-heading-to-better-describe-referen.patch > v3-0003-Better-section-heading-for-plpgsql-exception-trap.patch > v3-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch > v3-0005-Improve-sentences-in-overview-of-system-configura.patch > v3-0006-Provide-examples-of-listing-all-settings.patch > v3-0007-Cleanup-summary-of-role-powers.patch > v3-0008-Explain-the-difference-between-role-attributes-an.patch > v3-0009-Document-the-oidvector-type.patch > v3-0010-Improve-sentences-about-the-significance-of-the-s.patch > v3-0011-Add-a-sub-section-to-describe-schema-resolution.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-01T00:47:34Z
Version 4. Added: v4-0012-Explain-role-management.patch On Mon, 25 Sep 2023 23:37:44 -0500 "Karl O. Pinc" <kop@karlpinc.com> wrote: > > On Mon, 25 Sep 2023 17:55:59 -0500 > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > > > Once done you can do "git format-patch origin/master -v 1" which > > > > will generate a set of n patches named v1-0001 through v1-000n. > > > I am not particularly confident in the top-line commit > > > descriptions. > > > > > The bulk of the commit descriptions are very wordy > > > > > Listing all the attachments here for future discussion: v4-0001-Change-section-heading-to-better-reflect-saving-a.patch v4-0002-Change-section-heading-to-better-describe-referen.patch v4-0003-Better-section-heading-for-plpgsql-exception-trap.patch v4-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v4-0005-Improve-sentences-in-overview-of-system-configura.patch v4-0006-Provide-examples-of-listing-all-settings.patch v4-0007-Cleanup-summary-of-role-powers.patch v4-0008-Explain-the-difference-between-role-attributes-an.patch v4-0009-Document-the-oidvector-type.patch v4-0010-Improve-sentences-about-the-significance-of-the-s.patch v4-0011-Add-a-sub-section-to-describe-schema-resolution.patch v4-0012-Explain-role-management.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-01T23:16:57Z
Version 5 Changed word order in a sentence: v5-0012-Explain-role-management.patch Added a hyperlink: v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch Added 3 index entries: v5-0014-Add-index-entries-for-parallel-safety.patch > On Mon, 25 Sep 2023 23:37:44 -0500 > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > On Mon, 25 Sep 2023 17:55:59 -0500 > > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > > > > > Once done you can do "git format-patch origin/master -v 1" > > > > > which will generate a set of n patches named v1-0001 through > > > > > v1-000n. > > > > > I am not particularly confident in the top-line commit > > > > descriptions. > > > > > > > The bulk of the commit descriptions are very wordy > > > > > > > Listing all the attachments here for future discussion: v5-0001-Change-section-heading-to-better-reflect-saving-a.patch v5-0002-Change-section-heading-to-better-describe-referen.patch v5-0003-Better-section-heading-for-plpgsql-exception-trap.patch v5-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v5-0005-Improve-sentences-in-overview-of-system-configura.patch v5-0006-Provide-examples-of-listing-all-settings.patch v5-0007-Cleanup-summary-of-role-powers.patch v5-0008-Explain-the-difference-between-role-attributes-an.patch v5-0009-Document-the-oidvector-type.patch v5-0010-Improve-sentences-about-the-significance-of-the-s.patch v5-0011-Add-a-sub-section-to-describe-schema-resolution.patch v5-0012-Explain-role-management.patch v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch v5-0014-Add-index-entries-for-parallel-safety.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-01T23:18:07Z
Version 5, this time with attachments. Changed word order in a sentence: v5-0012-Explain-role-management.patch Added a hyperlink: v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch Added 3 index entries: v5-0014-Add-index-entries-for-parallel-safety.patch > On Mon, 25 Sep 2023 23:37:44 -0500 > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > On Mon, 25 Sep 2023 17:55:59 -0500 > > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > > > > > Once done you can do "git format-patch origin/master -v 1" > > > > > which will generate a set of n patches named v1-0001 through > > > > > v1-000n. > > > > > I am not particularly confident in the top-line commit > > > > descriptions. > > > > > > > The bulk of the commit descriptions are very wordy > > > > > > > Listing all the attachments here for future discussion: v5-0001-Change-section-heading-to-better-reflect-saving-a.patch v5-0002-Change-section-heading-to-better-describe-referen.patch v5-0003-Better-section-heading-for-plpgsql-exception-trap.patch v5-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v5-0005-Improve-sentences-in-overview-of-system-configura.patch v5-0006-Provide-examples-of-listing-all-settings.patch v5-0007-Cleanup-summary-of-role-powers.patch v5-0008-Explain-the-difference-between-role-attributes-an.patch v5-0009-Document-the-oidvector-type.patch v5-0010-Improve-sentences-about-the-significance-of-the-s.patch v5-0011-Add-a-sub-section-to-describe-schema-resolution.patch v5-0012-Explain-role-management.patch v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch v5-0014-Add-index-entries-for-parallel-safety.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-02T20:18:32Z
On Sun, 1 Oct 2023 18:18:07 -0500 "Karl O. Pinc" <kop@karlpinc.com> wrote: Version 6 Added: v6-0015-Trigger-authors-need-not-worry-about-parallelism.patch Can't say if this is an awesome idea or not. (Might have saved me time.) Read the commit message for a justification. > > On Mon, 25 Sep 2023 23:37:44 -0500 > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > On Mon, 25 Sep 2023 17:55:59 -0500 > > > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > > > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > > > > > > > Once done you can do "git format-patch origin/master -v 1" > > > > > > which will generate a set of n patches named v1-0001 through > > > > > > v1-000n. > > > > > > > I am not particularly confident in the top-line commit > > > > > descriptions. > > > > > > > > > The bulk of the commit descriptions are very wordy > > > > > > > > > Listing all the attachments here for future discussion: v6-0001-Change-section-heading-to-better-reflect-saving-a.patch v6-0002-Change-section-heading-to-better-describe-referen.patch v6-0003-Better-section-heading-for-plpgsql-exception-trap.patch v6-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v6-0005-Improve-sentences-in-overview-of-system-configura.patch v6-0006-Provide-examples-of-listing-all-settings.patch v6-0007-Cleanup-summary-of-role-powers.patch v6-0008-Explain-the-difference-between-role-attributes-an.patch v6-0009-Document-the-oidvector-type.patch v6-0010-Improve-sentences-about-the-significance-of-the-s.patch v6-0011-Add-a-sub-section-to-describe-schema-resolution.patch v6-0012-Explain-role-management.patch v6-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch v6-0014-Add-index-entries-for-parallel-safety.patch v6-0015-Trigger-authors-need-not-worry-about-parallelism.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-03T17:52:48Z
On Mon, 2 Oct 2023 15:18:32 -0500 "Karl O. Pinc" <kop@karlpinc.com> wrote: Version 7 Added: v7-0016-Predicate-locks-are-held-per-cluster-not-per-data.patch > > > On Mon, 25 Sep 2023 23:37:44 -0500 > > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > > > On Mon, 25 Sep 2023 17:55:59 -0500 > > > > > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > > > > > > > > > > On Mon, 25 Sep 2023 14:14:37 +0200 > > > > > > Daniel Gustafsson <daniel@yesql.se> wrote: > > > > > > > > > > > > Once done you can do "git format-patch origin/master -v 1" > > > > > > > which will generate a set of n patches named v1-0001 > > > > > > > through v1-000n. > > > > > > > > > I am not particularly confident in the top-line commit > > > > > > descriptions. > > > > > > > > > > > The bulk of the commit descriptions are very wordy > > > > > > > > > > > Listing all the attachments here for future discussion: v7-0001-Change-section-heading-to-better-reflect-saving-a.patch v7-0002-Change-section-heading-to-better-describe-referen.patch v7-0003-Better-section-heading-for-plpgsql-exception-trap.patch v7-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch v7-0005-Improve-sentences-in-overview-of-system-configura.patch v7-0006-Provide-examples-of-listing-all-settings.patch v7-0007-Cleanup-summary-of-role-powers.patch v7-0008-Explain-the-difference-between-role-attributes-an.patch v7-0009-Document-the-oidvector-type.patch v7-0010-Improve-sentences-about-the-significance-of-the-s.patch v7-0011-Add-a-sub-section-to-describe-schema-resolution.patch v7-0012-Explain-role-management.patch v7-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch v7-0014-Add-index-entries-for-parallel-safety.patch v7-0015-Trigger-authors-need-not-worry-about-parallelism.patch v7-0016-Predicate-locks-are-held-per-cluster-not-per-data.patch Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
David G. Johnston <david.g.johnston@gmail.com> — 2023-10-03T21:51:31Z
On Tue, Oct 3, 2023 at 10:56 AM Karl O. Pinc <kop@karlpinc.com> wrote: > On Mon, 2 Oct 2023 15:18:32 -0500 > "Karl O. Pinc" <kop@karlpinc.com> wrote: > > Version 7 > > 0001 - I would just call the section: Capturing Command Results into Variables I would add commentary in there that it is only possible for variables to take on single value at any given time and so in order to handle multiple row results you need to instantiate a loop as per 43.6.6 0002 - {Inferred | Indirect} Types ? We are already in the Declarations section so the fact we are declaring new variables is already covered. "Instead of literally writing a type name you can write variable%TYPE and the system will indirectly apply the then-current type of the named variable to the newly declared variable." (using "copy the then-current" reads pretty well and makes the existing title usable...) 0003 - The noun "Exception" here means "deviating from the normal flow of the code", not, "A subclass of error". I don't see this title change being particularly beneficial. 0004 - Agreed, but "You can raise an error explicitly as described in "Errors and Messages". I would not use the phrase "raise an exception", it doesn't fit. 0005 - This tone of voice is used throughout the introductory documentation sections, this single change doesn't seem warranted. 0006 - Useful. The view itself provides all configuration parameters known to the system, the "or selected" isn't true of the view itself, and it seems to go without saying that the user can add a where clause to any query they write using that view. At most I'd make one of the examples include a where clause. 0007 - I'm leaning toward this area being due for some improvement, especially given the v16 changes bring new attention to it, but this patch doesn't scream "improvement" to me. 0008 - Same as 0007. INHERIT is no longer an attribute though, it is a property of membership. This seems more acceptable on its own but I'd need more time to take in the big picture myself. That's it for now. I'll look over the other 8 when I can. David J. -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-10-03T23:15:49Z
On Tue, 3 Oct 2023 14:51:31 -0700 "David G. Johnston" <david.g.johnston@gmail.com> wrote: > 0001 - I would just call the section: > Capturing Command Results into Variables I like your wording a lot. Let's use it! > I would add commentary in there that it is only possible for > variables to take on single value at any given time and so in order > to handle multiple row results you need to instantiate a loop as per > 43.6.6 That sounds reasonable. Let me see what I can come up with. I'll do it in a separate commit. > 0002 - {Inferred | Indirect} Types ? > We are already in the Declarations section so the fact we are > declaring new variables is already covered. I agree. But the problem is that the section title needs to stand on it's own when the table of contents is scanned. By that I don't mean that getting context from a "Declaration" higher level section is somehow out-of-bounds, but that neither "inferred" nor "indirect" has a recognizable meaning unless the section body itself is read. I thought about: Referencing Existing Types But the problem with that is that the reader does not know that this has to do with the types of existing objects rather than working with user-defined types (or something else). Also, I kind of like "re-using". Shorter, simpler, word. There is: Re-Using the Type of Objects "Objects" is not very clear. Variables are very different from columns. It seemed best to just write it out. > "Instead of literally writing a type name you can write variable%TYPE > and the system will indirectly apply the then-current type of the > named variable to the newly declared variable." I've no objection to the section leading with a summary sentence like this. The trouble is coming up with something good. I'd go with "You can reference the data type of an existing column or variable with the %TYPE notation. The syntax is:" Shorter and simpler. Along with this change, it might be nice to move the "By using %TYPE ..." paragraph to after the first example (before the first paragraph). But this is really feature creep for this commit. :) > (using "copy the > then-current" reads pretty well and makes the existing title > usable...) I disagree. The title needs to be understandable without reading the section body. > > 0003 - The noun "Exception" here means "deviating from the normal > flow of the code", not, "A subclass of error". I don't see this > title change being particularly beneficial. Isn't the entire section about "deviating from the normal flow of the code"? That's what makes me want "Exception" in the section title. > 0004 - Agreed, but "You can raise an error explicitly as described in > "Errors and Messages". I would not use the phrase "raise an > exception", it doesn't fit. I like the brevity of your sentence. And you're right that the sentence does not flow as written. How about: You can raise an exception to throw an error as described in "Errors and Messages". ? I remain (overly?) focused on the word "exception", since that's whats in the brain of the user that's writing RAISE EXCEPTION. It matters if exceptions and errors are different. If they're not, then it also matters since it's exceptions that the user's code raises. > 0005 - This tone of voice is used throughout the introductory > documentation sections, this single change doesn't seem warranted. Ok. I'll drop it unless somebody else chimes in. > 0006 - Useful. The view itself provides all configuration parameters > known to the system, the "or selected" isn't true of the view itself, > and it seems to go without saying that the user can add a where > clause to any query they write using that view. At most I'd make one > of the examples include a where clause. Good points. I'll get rid of the ", or selected,". May as well leave the examples as short as possible. Less is more. :) > 0007 - I'm leaning toward this area being due for some improvement, > especially given the v16 changes bring new attention to it, but this > patch doesn't scream "improvement" to me. Let's see how it looks with 0012, which uses the vocabulary. I do like the "Roles therefore control who has what access to which objects." sentence. I was shooting for shorter sentences, but then when I broke the existing sentences into pieces I couldn't resist adding text. > 0008 - Same as 0007. INHERIT is no longer an attribute though, it is > a property of membership. (!) I'm going to have to pay more attention. > This seems more acceptable on its own but > I'd need more time to take in the big picture myself. It's the big picture that I'm trying to draw. 0007, 0008, and 0012 all kind of go together. It may be worth forking the email thread, or something. Have you any thoughts on the "permissions", "privleges" and "attributes" vocabulary/concepts used in this area? Thanks very much for the review. I'm going to wait a bit before incorporating your suggestions and sending in another patch set in case Daniel chimes in. (I'm slightly nervous about the renumbering making the thread hard to follow.) Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
David G. Johnston <david.g.johnston@gmail.com> — 2023-10-04T02:00:18Z
On Tue, Oct 3, 2023 at 4:15 PM Karl O. Pinc <kop@karlpinc.com> wrote: > On Tue, 3 Oct 2023 14:51:31 -0700 > "David G. Johnston" <david.g.johnston@gmail.com> wrote: > > Isn't the entire section about "deviating from the normal flow of the > code"? That's what makes me want "Exception" in the section title. > It is about how error handling in a procedure diverts the flow from the normal code path to some other code path - what that path is labelled is less important than the thing that causes the diversion - an error. > ? I remain (overly?) focused on the word "exception", since that's > whats in the brain of the user that's writing RAISE EXCEPTION. > It matters if exceptions and errors are different. If they're > not, then it also matters since it's exceptions that the user's > code raises. > > It's unfortunate the keyword to raise the message level "ERROR" is "EXCEPTION" in that command but I'd rather simply handle that one anomaly that make the rest of the system use the word exception, especially seem to be fairly consistent in our usage of ERROR already. I'm sympathetic that other systems out there also encourage the usage of exception in this context instead of error - but not to the point of opening up this long-standing decision for rework. > Have you any thoughts on the "permissions", "privleges" and > "attributes" vocabulary/concepts used in this area? > I think we benefit from being able to equate permissions and privileges and trying to separate them is going to be more harmful than helpful. The limited things that role attributes permit, and how they fall outside the privilege/permission concept as we use it, isn't something that I've noticed is a problem that needs addressing. (I'm slightly > nervous about the renumbering making the thread hard to follow.) > > 0009 - Something just seems off with this one. Unless there are more places with this type in use I would just move the relevant notes (i.e., the one in proallargtypes) to that column and be done with it. If there are multiple places then moving the notes to the main docs and cross-referencing to them seems warranted. I also wouldn't call it legacy. 0010 - When creating new objects, if a schema qualification is not given with the name the first extant entry in the search_path is chosen; then an error will be raised should the supplied name already exist in that schema. In contexts where the object must already exist, but its name is not schema qualified, the extant search_path schemas will be consulted serially until one of them contains an appropriate object, returning it, or all schemas are consulted, resulting in an object not found error. I'm not seeing much value in presenting the additional user/public details here. Especially as it would then seem appropriate to include pg_temp. And now we have to deal with the fact that by default the public schema isn't so public anymore. David J.
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
David G. Johnston <david.g.johnston@gmail.com> — 2023-10-04T06:25:26Z
Extending my prior email which is now redundant. On Tue, Oct 3, 2023 at 7:00 PM David G. Johnston <david.g.johnston@gmail.com> wrote: > On Tue, Oct 3, 2023 at 4:15 PM Karl O. Pinc <kop@karlpinc.com> wrote: > >> On Tue, 3 Oct 2023 14:51:31 -0700 >> "David G. Johnston" <david.g.johnston@gmail.com> wrote: >> >> Isn't the entire section about "deviating from the normal flow of the >> code"? That's what makes me want "Exception" in the section title. >> > > It is about how error handling in a procedure diverts the flow from the > normal code path to some other code path - what that path is labelled is > less important than the thing that causes the diversion - an error. > > >> ? I remain (overly?) focused on the word "exception", since that's >> whats in the brain of the user that's writing RAISE EXCEPTION. >> It matters if exceptions and errors are different. If they're >> not, then it also matters since it's exceptions that the user's >> code raises. >> >> > It's unfortunate the keyword to raise the message level "ERROR" is > "EXCEPTION" in that command but I'd rather simply handle that one anomaly > that make the rest of the system use the word exception, especially seem to > be fairly consistent in our usage of ERROR already. I'm sympathetic that > other systems out there also encourage the usage of exception in this > context instead of error - but not to the point of opening up this > long-standing decision for rework. > > >> Have you any thoughts on the "permissions", "privleges" and >> "attributes" vocabulary/concepts used in this area? >> > > I think we benefit from being able to equate permissions and privileges > and trying to separate them is going to be more harmful than helpful. The > limited things that role attributes permit, and how they fall outside the > privilege/permission concept as we use it, isn't something that I've > noticed is a problem that needs addressing. > > > (I'm slightly >> nervous about the renumbering making the thread hard to follow.) >> >> > 0009 - Something just seems off with this one. Unless there are more > places with this type in use I would just move the relevant notes (i.e., > the one in proallargtypes) to that column and be done with it. If there > are multiple places then moving the notes to the main docs and > cross-referencing to them seems warranted. I also wouldn't call it legacy. > > 0010 - > > When creating new objects, if a schema qualification is not given with the > name the first extant entry in the search_path is chosen; then an error > will be raised should the supplied name already exist in that schema. > In contexts where the object must already exist, but its name is not > schema qualified, the extant search_path schemas will be consulted serially > until one of them contains an appropriate object, returning it, or all > schemas are consulted, resulting in an object not found error. > > I'm not seeing much value in presenting the additional user/public details > here. Especially as it would then seem appropriate to include pg_temp. > And now we have to deal with the fact that by default the public schema > isn't so public anymore. > > 0011 - (first pass, going from memory, might have missed some needed details) Aside from non-atomic SQL routine bodies (functions and procedures) the result of the server executing SQL sent by the connected client does not result in raw SQL, or textual expressions, being stored for later evaluation. All objects are identified (or created) during execution and their effects stored within the system catalogs and assigned system identifiers (oids) to provide an absolute and immutable reference to be used while establishing inter-object dependencies. In short, indirect actions taken by the server, based upon stored knowledge, can and often will execute while in a search_path that only contains the pg_catalog schema so that the stored knowledge can be found. For routines written in any language except Atomic SQL the textual body of the routine is stored as-is within the database. When executing such a routine the (parent) session basically opens up a new connection to the server (one per routine) and within that new sub-session sends the SQL contained within the routine to the server for execution just like any other client, and therefore any object references present in that SQL need to be resolved to a schema as previously discussed. By default, upon connecting, the newly created session is updated so that its settings take on the current values in the parent session. When authoring a routine this is often undesirable as the behavior of the routine now depends upon an environment that is not definitively known to the routine author. Schema-qualifying object references within the routine body is one tool to remove such uncertainty. Another is by using the SET clause of the relevant CREATE SQL Command to specify what the value of important settings are to be. The key takeaway from the preceding two paragraphs is that because routines are stored as text and their settings resolved at execution time, and indirect server actions can invoke those routines with a pg_catalog only search_path, any routine that potentially can be invoked in that manner and makes use of search_path should either be modified to eliminate such use or define the required search_path via the SET option during its creation or replacement. 0012 - (this has changed recently too, I'm not sure how this fits within the rest. I still feel like something is missing even in my revision but not sure what or if it is covered sufficiently nearby) All roles are ultimately owned and managed by the bootstrap superuser, who can establish trees of groups and users upon which the object permission granting system works. By enabling the CREATEROLE attribute on a user a superuser can delegate role creation to other people (it is inadvisable to enable CREATEROLE on a group) who can then construct their own trees of groups and users. (not sure how true this is still but something to consider in terms of big picture role setups) It is likewise inadvisable to create multiple superusers since in practice their actions in many cases can be made to look attributable to the bootstrap superuser. It is necessary to enlist services outside of PostgreSQL to adequately establish auditing in a multi-superuser setup. Note my intentional use of users and groups here. We got rid of the distinction with CREATE ROLE but in terms of system administration they still have, IMO, significant utility. 0013 - +1 0014 - +1 0015 - I'd almost rather only note in CREATE FUNCTION that PARALLEL does not matter for a trigger returning function as triggers only execute in cases of data writing which precludes using parallelism. Which is indeed what the documentation explicitly calls out in "When Can Parallel Query Be Used?" so it isn't inference from omission. I don't have a problem saying in the trigger documentation, maybe at the very end: The functions that triggers execute are more appropriately considered procedures but since the later feature did not exist when triggers were implemented precedent compels the dba to write their routines as functions. As a consequence, function attributes such as PARALLEL, and WINDOW, are possible to define on a function that is to be used as a trigger but will have no effect. (though I would think at least some of these get rejected outright) 0016 - not within my knowledge base David J.
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Shubham Khanna <khannashubham1197@gmail.com> — 2023-11-30T10:32:28Z
On Thu, Nov 30, 2023 at 3:59 PM David G. Johnston <david.g.johnston@gmail.com> wrote: > > Extending my prior email which is now redundant. > > On Tue, Oct 3, 2023 at 7:00 PM David G. Johnston <david.g.johnston@gmail.com> wrote: >> >> On Tue, Oct 3, 2023 at 4:15 PM Karl O. Pinc <kop@karlpinc.com> wrote: >>> >>> On Tue, 3 Oct 2023 14:51:31 -0700 >>> "David G. Johnston" <david.g.johnston@gmail.com> wrote: >>> >>> Isn't the entire section about "deviating from the normal flow of the >>> code"? That's what makes me want "Exception" in the section title. >> >> >> It is about how error handling in a procedure diverts the flow from the normal code path to some other code path - what that path is labelled is less important than the thing that causes the diversion - an error. >> >>> >>> ? I remain (overly?) focused on the word "exception", since that's >>> whats in the brain of the user that's writing RAISE EXCEPTION. >>> It matters if exceptions and errors are different. If they're >>> not, then it also matters since it's exceptions that the user's >>> code raises. >>> >> >> It's unfortunate the keyword to raise the message level "ERROR" is "EXCEPTION" in that command but I'd rather simply handle that one anomaly that make the rest of the system use the word exception, especially seem to be fairly consistent in our usage of ERROR already. I'm sympathetic that other systems out there also encourage the usage of exception in this context instead of error - but not to the point of opening up this long-standing decision for rework. >> >>> >>> Have you any thoughts on the "permissions", "privleges" and >>> "attributes" vocabulary/concepts used in this area? >> >> >> I think we benefit from being able to equate permissions and privileges and trying to separate them is going to be more harmful than helpful. The limited things that role attributes permit, and how they fall outside the privilege/permission concept as we use it, isn't something that I've noticed is a problem that needs addressing. >> >> >>> (I'm slightly >>> nervous about the renumbering making the thread hard to follow.) >>> >> >> 0009 - Something just seems off with this one. Unless there are more places with this type in use I would just move the relevant notes (i.e., the one in proallargtypes) to that column and be done with it. If there are multiple places then moving the notes to the main docs and cross-referencing to them seems warranted. I also wouldn't call it legacy. >> >> 0010 - >> >> When creating new objects, if a schema qualification is not given with the name the first extant entry in the search_path is chosen; then an error will be raised should the supplied name already exist in that schema. >> In contexts where the object must already exist, but its name is not schema qualified, the extant search_path schemas will be consulted serially until one of them contains an appropriate object, returning it, or all schemas are consulted, resulting in an object not found error. >> >> I'm not seeing much value in presenting the additional user/public details here. Especially as it would then seem appropriate to include pg_temp. And now we have to deal with the fact that by default the public schema isn't so public anymore. >> > > 0011 - (first pass, going from memory, might have missed some needed details) > > Aside from non-atomic SQL routine bodies (functions and procedures) the result of the server executing SQL sent by the connected client does not result in raw SQL, or textual expressions, being stored for later evaluation. All objects are identified (or created) during execution and their effects stored within the system catalogs and assigned system identifiers (oids) to provide an absolute and immutable reference to be used while establishing inter-object dependencies. In short, indirect actions taken by the server, based upon stored knowledge, can and often will execute while in a search_path that only contains the pg_catalog schema so that the stored knowledge can be found. > > For routines written in any language except Atomic SQL the textual body of the routine is stored as-is within the database. When executing such a routine the (parent) session basically opens up a new connection to the server (one per routine) and within that new sub-session sends the SQL contained within the routine to the server for execution just like any other client, and therefore any object references present in that SQL need to be resolved to a schema as previously discussed. By default, upon connecting, the newly created session is updated so that its settings take on the current values in the parent session. When authoring a routine this is often undesirable as the behavior of the routine now depends upon an environment that is not definitively known to the routine author. Schema-qualifying object references within the routine body is one tool to remove such uncertainty. Another is by using the SET clause of the relevant CREATE SQL Command to specify what the value of important settings are to be. > > The key takeaway from the preceding two paragraphs is that because routines are stored as text and their settings resolved at execution time, and indirect server actions can invoke those routines with a pg_catalog only search_path, any routine that potentially can be invoked in that manner and makes use of search_path should either be modified to eliminate such use or define the required search_path via the SET option during its creation or replacement. > > 0012 - (this has changed recently too, I'm not sure how this fits within the rest. I still feel like something is missing even in my revision but not sure what or if it is covered sufficiently nearby) > > All roles are ultimately owned and managed by the bootstrap superuser, who can establish trees of groups and users upon which the object permission granting system works. By enabling the CREATEROLE attribute on a user a superuser can delegate role creation to other people (it is inadvisable to enable CREATEROLE on a group) who can then construct their own trees of groups and users. > > (not sure how true this is still but something to consider in terms of big picture role setups) > It is likewise inadvisable to create multiple superusers since in practice their actions in many cases can be made to look attributable to the bootstrap superuser. It is necessary to enlist services outside of PostgreSQL to adequately establish auditing in a multi-superuser setup. > > Note my intentional use of users and groups here. We got rid of the distinction with CREATE ROLE but in terms of system administration they still have, IMO, significant utility. > > 0013 - +1 > 0014 - +1 > > 0015 - I'd almost rather only note in CREATE FUNCTION that PARALLEL does not matter for a trigger returning function as triggers only execute in cases of data writing which precludes using parallelism. Which is indeed what the documentation explicitly calls out in "When Can Parallel Query Be Used?" so it isn't inference from omission. > > I don't have a problem saying in the trigger documentation, maybe at the very end: > > The functions that triggers execute are more appropriately considered procedures but since the later feature did not exist when triggers were implemented precedent compels the dba to write their routines as functions. As a consequence, function attributes such as PARALLEL, and WINDOW, are possible to define on a function that is to be used as a trigger but will have no effect. (though I would think at least some of these get rejected outright) > > 0016 - not within my knowledge base > >I reviewed the Patch and found a few changes. Please have a look at them: -v7-0002-Change-section-heading-to-better-describe-referen.patch "Re-Using the Type of Columns and Variables" seems adequate. Getting something in there about declartions seems too wordy. I thought perhaps "Referencing" instead of "Re-Using", but "referencing" isn't perfect and "re-using" is generic enough, shorter, and simpler to Here 'declartions' should be replaced with 'declarations'. -v7-0012-Explain-role-management.patch + The managment of most database objects is by way of granting some role Here 'managment' should be replaced with 'management'. -v7-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch Is is nice to have a link in the reference material to a full discussion. Here 'is' should be removed. -v7-0015-Trigger-authors-need-not-worry-about-parallelism.patch Plus, this patch adds an index entry so the new verbage is easy to find for those who do investigate. Here 'verbage' should be replaced with 'verbiage'. -v7-0016-Predicate-locks-are-held-per-cluster-not-per-data.patch This is a significant corner case and so should be documented. It is also somewhat suprising since the databases within a cluster are otherwise isolated, at least from the user's perspective. Here 'suprising' should be replaced with 'surprising'. Predicate locks are held per-cluster, not per database. + This means that serializeable transactions in one database can have + effects in another. + Long running serializeable transactions, as might occur accidentally + when + <link linkend="app-psql-meta-command-pset-pager">pagination</link> + halts <link linkend="app-psql">psql</link> output, can have + significant inter-database effects. + These include exhausting available predicate locks and + cluster-wide <link linkend="ports12">WAL checkpoint delay</link>. + When making use of serializeable transactions consider having + separate clusters for production and non-production use. Here 'serializeable' should be replaced with 'serializable'. Thanks and Regards, Shubham Khanna.
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2023-12-01T14:00:39Z
Hello, Thank you all for your help. I won't be able to submit new patches based on reviews for 2 weeks. On Thu, 30 Nov 2023 16:02:28 +0530 Shubham Khanna <khannashubham1197@gmail.com> wrote: <snip> > -v7-0012-Explain-role-management.patch > > + The managment of most database objects is by way of granting some > role > > Here 'managment' should be replaced with 'management'. <snip> Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Andrey Borodin <x4mmm@yandex-team.ru> — 2024-03-28T12:16:17Z
> On 1 Dec 2023, at 19:00, Karl O. Pinc <kop@karlpinc.com> wrote: > > I won't be able to submit > new patches based on reviews for 2 weeks. Hi everyone! Is there any work going on? Maybe is someone interested in moving this forward? Thanks! Best regards, Andrey Borodin.
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Robert Treat <rob@xzilla.net> — 2024-03-28T12:28:16Z
On Thu, Mar 28, 2024 at 8:16 AM Andrey M. Borodin <x4mmm@yandex-team.ru> wrote: > > On 1 Dec 2023, at 19:00, Karl O. Pinc <kop@karlpinc.com> wrote: > > > > I won't be able to submit > > new patches based on reviews for 2 weeks. > > Hi everyone! > > Is there any work going on? Maybe is someone interested in moving this forward? > > Thanks! > Hey Andrey, I spoke with Karl briefly on this and he is working on getting an updated patch together. The work now involves incorporating feedback and some rebasing, but hopefully we will see something in the next few days. Robert Treat https://xzilla.net
-
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Karl O. Pinc <kop@karlpinc.com> — 2024-03-30T06:39:35Z
On Thu, 28 Mar 2024 08:28:16 -0400 Robert Treat <rob@xzilla.net> wrote: > I spoke with Karl briefly on this and he is working on getting an > updated patch together. The work now involves incorporating feedback > and some rebasing, but hopefully we will see something in the next few > days. Well, Friday has come and gone and I've not gotten to this. I'll see if I can spend time tomorrow. Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein -
Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector
Andrey Borodin <x4mmm@yandex-team.ru> — 2024-03-30T09:11:38Z
> On 30 Mar 2024, at 11:39, Karl O. Pinc <kop@karlpinc.com> wrote: > > Well, Friday has come and gone and I've not gotten to this. > I'll see if I can spend time tomorrow. No worries, Karl! I just wanted to know if anyone is interested in this thread, and, now is obvious that you are. Thanks for your work! Best regards, Andrey Borodin.