Re: Question about role attributes docs

On Tue, Feb 15, 2022 at 1:32 PM Shinya Kato <Shinya11(dot)Kato(at)oss(dot)nttdata(dot)com>
wrote:

> On 2022-01-12 02:07, Laurenz Albe wrote:
> > On Tue, 2022-01-11 at 16:40 +0900, Shinya Kato wrote:
> >> I have a question about the documentation on ROLE.
> >>
> >> According to [1], INHERIT and BYPASSRLS can be specified when
> >> executing
> >> the CREATE ROLE command. However, there is no such description in Role
> >> Attributes in [2]. Are these concepts different from Role Attributes?
> >> Or
> >> are they just not documented? If they need to be documented, I'll
> >> create
> >> a patch.
> >>
> >> [1] https://www.postgresql.org/docs/devel/sql-createrole.html
> >> [2] https://www.postgresql.org/docs/devel/role-attributes.html
> >
> > I think that is indeed an omission, and adding documentation would be a
> > good idea.
> Thanks! I created the patch, and attached it.
>
> > On the other hand, a lot of that information is more or less
> > a duplicate of the CREATE ROLE documentation. I wonder if the latter
> > page could be removed altogether.
> I think there is certainly a lot of overlap. However, I think that the
> SQL commands page and the database roles page should exist separately,
> and should be maintained as they are because there are parts that do not
> overlap (for example, IN ROLE and ADMIN).
>
> --
> Regards,
>
> --
> Shinya Kato
> Advanced Computing Technology Center
> Research and Development Headquarters
> NTT DATA CORPORATION

May I suggest replacing the following verbiage in your patch
+ A role is needed to permission to inherit privileges of roles it
is a member of.
+ (except for superusers, since those bypass all permission checks).
+ If not specified, <literal>INHERIT</literal> is the default, so to
create such a role, use either:

with clearer wording such as the following:

A role can explicitly be restricted at time of creation from inheriting
privileges of
roles it is a member of (except for superusers, since those bypass all
permission checks.)
Restricting privileges is done by the <literal>NOINHERIT</literal> option.
If no option is specified, <literal>INHERIT</literal> is the default. So to
create a role that inherits
privileges, use either:

Regards,

Swaha Miller
Amazon Web Services