Re: CREATE ROLE inheritance details

On Fri, Jan 26, 2024 at 5:18 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

>
> Just a reminder, this is for PG 16 and master.
>
>
<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.

<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 leave 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.

@@ -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

@@ -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.

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...

To modify that attributes of
+ an existing membership, simply specify the membership with updated
+ attribute values.

attribute s/b option

<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.

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.

David J.