Re: improve predefined roles documentation

On Thu, Jun 20, 2024 at 07:57:16PM -0700, David G. Johnston wrote:
> I like this.  Losing the table turned out to be ok.  Thank you.

Awesome.

> I would probably put pg_monitor first in the list.

Done.

> + A user granted this role cannot however send signals to a backend owned
> by a superuser.
> 
> Remove "however", or put commas around it.  I prefer the first option.

This sentence caught my eye earlier, too, because it seems to imply that a
superuser granted this role cannot signal superuser-owned backends.  I
changed it to the following:

    Note that this role does not permit signaling backends owned by a
    superuser.

How does that sound?

> Do we really need to repeat "even without having it explicitly" everywhere?

Removed.

> + This role does not have the role attribute BYPASSRLS set.
> 
> Even if it did, that attribute isn't inherited anyway...
> 
> "This role is still governed by any row level security policies that may be
> in force.  Consider setting the BYPASSRLS attribute on member roles."
> 
> (assuming they intend it to be ALL data then doing the bypassrls even if
> they are not today using it doesn't hurt)

How does something like the following sound?

    This role does not bypass row-level security (RLS) policies.  If RLS is
    being used, an administrator may wish to set BYPASSRLS on roles which
    this role is granted to.

> pg_stat_scan_tables - This explanation leaves me wanting more.  Maybe give
> an example of such a function?  I think the bar is set a bit too high just
> talking about a specific lock level.

I was surprised to learn that this role only provides privileges for
functions in contrib/ modules.  Anyway, added an example.

> "As these roles are able to access any file on the server file system,"
> 
> We forbid running under root so this isn't really true.  They do have
> operating system level access logged in as the database process owner.
> They are able to access all PostgreSQL files on the server file system and
> usually can run a wide-variety of commands on the server.

I just deleted this clause.

> "access, therefore great care should be taken"
> 
> I would go with:
> 
> "access.  Great care should be taken"
> 
> Seems more impactful as its own sentence then at the end of a long
> multi-part sentence.

Done.

> "server with COPY any other file-access functions." - s/with/using/

Done.

-- 
nathan