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 <br...@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 <br...@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 8dd2a6395c..d0d3d7ed64 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -133,24 +133,21 @@ in sync when changing the above synopsis!
<term><literal>NOINHERIT</literal></term>
<listitem>
<para>
- When the <literal>GRANT</literal> statement is used to confer
- membership in one role to another role, the <literal>GRANT</literal>
- may use the <literal>WITH INHERIT</literal> clause to specify whether
- the privileges of the granted role should be <quote>inherited</quote>
- by the new member. If the <literal>GRANT</literal> statement does not
- specify either inheritance behavior, the new <literal>GRANT</literal>
- will be created <literal>WITH INHERIT TRUE</literal> if the member
- role is set to <literal>INHERIT</literal> and to
- <literal>WITH INHERIT FALSE</literal> if it is set to
- <literal>NOINHERIT</literal>.
+ This affects the membership inheritance status when this
+ role is added as a member of another role, both in this and
+ future commands. Specifically, it controls the inheritance
+ status of memberships added with this command using the
+ <literal>IN ROLE</literal> clause, and in later commands using
+ the <literal>ROLE</literal> clause. It is also used as the
+ default inheritance status when adding this role as a member
+ using the <literal>GRANT</literal> command. If not specified,
+ <literal>INHERIT</literal> is the default.
</para>
<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 that controlled all runtime
+ membership checks for that role.
</para>
</listitem>
</varlistentry>
@@ -285,9 +282,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> option is specified. See the <xref
+ linkend="sql-grant"/> command, which has additional option
+ control during membership creation and to modify these options
+ after the new role is created.
</para>
</listitem>
</varlistentry>
@@ -297,8 +298,12 @@ in sync when changing the above synopsis!
<listitem>
<para>
The <literal>ROLE</literal> clause causes one or more specified
- existing roles to be automatically added as members of the new
- role. This in effect makes the new role a <quote>group</quote>.
+ existing roles to be automatically added as members, with the
+ <literal>SET</literal> option enabled. This in effect makes the
+ new role a <quote>group</quote>. Roles named in this clause
+ with role-level <literal>INHERIT</literal> options will have
+ <literal>INHERIT</literal> enabled in the new membership. New
+ memberships will have the <literal>ADMIN</literal> option disabled.
</para>
</listitem>
</varlistentry>
@@ -307,10 +312,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 has the same effect as
+ <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 the new role to others.
</para>
</listitem>
</varlistentry>
@@ -353,15 +358,19 @@ in sync when changing the above synopsis!
</para>
<para>
- The <literal>INHERIT</literal> attribute governs inheritance of grantable
- privileges (that is, access privileges for database objects and role
- memberships). It does not apply to the special role attributes set by
- <command>CREATE ROLE</command> and <command>ALTER ROLE</command>. For example, being
- a member of a role with <literal>CREATEDB</literal> privilege does not immediately
- grant the ability to create databases, even if <literal>INHERIT</literal> is set;
- it would be necessary to become that role via
- <link linkend="sql-set-role"><command>SET ROLE</command></link> before
- creating a database.
+ The role attributes defined here are non-inheritable, i.e., being a
+ member of a role with, e.g., <literal>CREATEDB</literal> will not
+ allow the member to create new databases even if the membership grant
+ has the <literal>INHERIT</literal> option. Of course, if the membership
+ grant has the <literal>SET</literal> option the member role would be able to
+ <link linkend="sql-set-role"><command>SET ROLE</command></link> to the
+ createdb role and then create a new database.
+ </para>
+
+ <para>
+ The membership grants created by the
+ <literal>IN ROLE</literal>, <literal>ROLE</literal>, and <literal>ADMIN</literal>
+ clauses have the role executing this command as the grantee.
</para>
<para>
@@ -460,8 +469,10 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <repl
<para>
The behavior specified by the SQL standard is most closely approximated
- by giving users the <literal>NOINHERIT</literal> attribute, while roles are
- given the <literal>INHERIT</literal> attribute.
+ creating SQL-standard users as <productname>PostgreSQL</productname>
+ roles with the <literal>NOINHERIT</literal> option, and SQL-standard
+ roles as <productname>PostgreSQL</productname> roles with the
+ <literal>INHERIT</literal> option.
</para>
<para>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 1ae5770fbb..ee53871713 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -249,11 +249,16 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
<para>
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 options <literal>SET</literal>, <literal>INHERIT</literal>,
+ and <literal>ADMIN</literal>; see <xref linkend="role-membership"/>
+ for details. Membership in a role is significant
because it potentially allows access to the privileges granted to a role
to each of its members, and potentially also the ability to make changes
to the role itself. However, the actual permissions conferred depend on
- the options associated with the grant.
+ the options associated with the grant. To modify that options of
+ an existing membership, simply specify the membership with updated
+ option values.
</para>
<para>
@@ -275,15 +280,14 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
</para>
<para>
- The <literal>INHERIT</literal> option, if it is set to
- <literal>TRUE</literal>, causes the member to inherit the privileges of
- the granted role. That is, it can automatically use whatever database
- privileges have been granted to that role. If set to
- <literal>FALSE</literal>, the member does not inherit the privileges
- of the granted role. If this clause is not specified, it defaults to
- true if the member role is set to <literal>INHERIT</literal> and to false
- if the member role is set to <literal>NOINHERIT</literal>.
- See <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.
+ The <literal>INHERIT</literal> attribute controls the inheritance status
+ of the new membership; see <xref linkend="role-membership"/> 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, new role membership defaults to the inheritance status
+ of the role being added. If an existing membership, the inheritance
+ option is unchanged.
</para>
<para>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 1c011ac62b..e026a4e271 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -409,10 +409,10 @@ REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceabl
than the original login role, and any database objects created are
considered owned by the group role not the login role. Second, member
roles that have been granted membership with the
- <literal>INHERIT</literal> option automatically have use
- of the privileges of those roles, including any
- privileges inherited by those roles.
- As an example, suppose we have done:
+ <literal>INHERIT</literal> option automatically have use of the
+ privileges of those directly or indirectly a member of, though the
+ chain stops at memberships lacking the inherit option. As an example,
+ suppose we have done:
<programlisting>
CREATE ROLE joe LOGIN;
CREATE ROLE admin;
