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