Re: CREATE ROLE inheritance details

On Sun, Jan 28, 2024 at 10:11:18AM -0700, David G. Johnston wrote:
> On Fri, Jan 26, 2024 at 5:18 PM Bruce Momjian <bruce@momjian.us> wrote:
>  <para>
> +        Role membership with the inherit attribute can automatically use
> +        whatever database privileges have been granted to all roles it
> +        is directly or indirectly a member of, though the chain stops
> +        at memberships lacking the inherit attribute.  Without role
> +        inheritance, the only other value of membership is the use of
> +        <command>SET ROLE</command>, assuming the membership chain has
> +        <literal>SET</literal> attributes.
>         </para>
> 
> 
> I really think it is clearer if we consistently call the property attached to
> the membership an "option" (the grant command calls them options) and restrict
> the word attribute to only when talking about the role property.  The following
> refers to the option.  I dislike burying this description about how the option
> works within create role like this.  It is already in chapter 22 and this
> attribute description should point the reader there, not repeat the
> information.

Okay, I made these changes in the attached version of the patch.

>         <para>
>          In <productname>PostgreSQL</productname> versions before 16,
> -        the <literal>GRANT</literal> statement did not support
> -        <literal>WITH INHERIT</literal>. Therefore, changing this role-level
> -        property would also change the behavior of already-existing grants.
> -        This is no longer the case.
> +        inheritance was a role-level attribute.  It could not be specified
> +        during role addition with <literal>GRANT</literal>, and changing
> +        this role-level property would also change the inheritance behavior
> +        of all existing memberships.  This is no longer the case.
>         </para>
> 
> My first reaction to the wording here is negative.
> 
> I agree that the pre-v16 behavior dynamic should be documented but maybe l
> eave a note with a bit more detail in chapter 22 and leave the following in
> place here:
> 
> Prior to version 16 this attribute directly controlled runtime privilege
> inheritance instead of now only providing a default for when role membership is
> established.

Okay, I simplified the explaination.

> @@ -285,9 +294,13 @@ in sync when changing the above synopsis!
>         <para>
>          The <literal>IN ROLE</literal> clause causes the new role to
>          be automatically added as a member of the specified existing
> -        roles. (Note that there is no option to add the new role as an
> -        administrator; use a separate <command>GRANT</command> command
> -        to do that.)
> +        roles. The new membership will have the <literal>SET</literal>
> +        option enabled and the <literal>ADMIN</literal> option disabled.
> +        The <literal>INHERIT</literal> option will be enabled unless the
> +        <literal>NOINHERIT</literal> attribute is specified.  See the <xref
> +        linkend="sql-grant"/> command, which has additional attribute
> +        control during membership creation and to modify these options
> +        after the new role is created.
>         </para>
> 
> additional attribute control s/b additional option control

Done

> @@ -307,10 +324,10 @@ in sync when changing the above synopsis!
>        <term><literal>ADMIN</literal> <replaceable class="parameter">role_name
> </replaceable></term>
>        <listitem>
>         <para>
> -        The <literal>ADMIN</literal> clause is like <literal>ROLE</literal>,
> -        but the named roles are added to the new role <literal>WITH ADMIN
> -        OPTION</literal>, giving them the right to grant membership in this
> role
> -        to others.
> +        The <literal>ADMIN</literal> clause is similar to
> +        <literal>ROLE</literal>, but the named roles are added as members
> +        of the new role with <literal>ADMIN</literal> enabled, giving
> +        them the right to grant membership in this role to others.
>         </para>
>        </listitem>
>       </varlistentry>
> 
> I was trying to be explicitly clear that the ADMIN clause is effectively
> additive to what ROLE does.  "similar to + but" makes it easier to interpret as
> something that only controls ADMIN, not SET or INHERIT.

Okay, I used new wording.

> The ADMIN clause behaves like ROLE but the ADMIN option is enabled.
> 
> And modify ROLE as such:
> 
> +        <literal>INHERIT</literal> enabled in the new membership.  New
> +        memberships will have the <literal>ADMIN</literal> option disabled.
> +  Use the ADMIN clause instead if you want the admin option enabled.
>  
>     This variant of the <command>GRANT</command> command grants membership
> -   in a role to one or more other roles.  Membership in a role is significant
> +   in a role to one or more other roles, and the modification of
> +   membership attributes.  Membership in a role is significant
> 
> and (allows) the modification of three membership options, set, inherit, and
> admin, described in chapter 22.  Membership in a role is significant...

Done.

> To modify that attributes of
> +   an existing membership, simply specify the membership with updated
> +   attribute values.
> 
> attribute s/b option

Done.

>    <para>
> @@ -275,15 +278,13 @@ GRANT <replaceable class="parameter">role_name</
> replaceable> [, ...] TO <replace
>    </para>
>  
>    <para>
> +   The <literal>INHERIT</literal> option controls the inheritance status
> +   of the new membership;  see <xref linkend="sql-createrole"/> for
> +   details on inheritance.  If it is set to <literal>TRUE</literal>,
> +   it causes the new member to inherit from the granted role. If
> +   set to <literal>FALSE</literal>, the new member does not inherit.
> +   If unspecified, it defaults to the inheritance status of the role
> +   being added.
>    </para>
>  
> Suggest linking to chapter 22, not create role.
K
Done.

> Unspecified has two outcomes: if the grant is establishing a new membership the
> inheritance "attribute" value of the role being added is used, if the grant is
> altering an existing membership the current value of the option is retained.

Done.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.