Re: Various small doc improvements; plpgsql, schemas, permissions, oidvector

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.