From: | Bruce Momjian <bruce(at)momjian(dot)us> |
---|---|
To: | "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> |
Cc: | Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>, PostgreSQL-documentation <pgsql-docs(at)postgresql(dot)org>, Robert Haas <robertmhaas(at)gmail(dot)com> |
Subject: | Re: CREATE ROLE inheritance details |
Date: | 2024-01-30 03:40:55 |
Message-ID: | Zbhvx4to5lx-pgGe@momjian.us |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
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(at)momjian(dot)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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachment | Content-Type | Size |
---|---|---|
role.diff | text/x-diff | 10.0 KB |
From | Date | Subject | |
---|---|---|---|
Next Message | PG Doc comments form | 2024-01-30 17:25:20 | SET ROLE versus SET SESSION AUTHORIZATION |
Previous Message | David G. Johnston | 2024-01-28 17:11:18 | Re: CREATE ROLE inheritance details |