0001-v2.patch

From ce4605354f1360662ffed6f0e239b2e06d107a85 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Wed, 17 Jan 2024 14:19:54 -0700
Subject: [PATCH] v2

---
 doc/src/sgml/ref/create_role.sgml | 81 +++++++++++++++++--------------
 1 file changed, 45 insertions(+), 36 deletions(-)

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 5c2b71bf69..f134feea27 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -133,29 +133,29 @@ in sync when changing the above synopsis!
       <term><literal>NOINHERIT</literal></term>
       <listitem>
        <para>
-        This controls the membership inheritance status when a new role
-        is added as a member using the <literal>IN ROLE</literal> clause,
-        when this role is later added as a member of a new role with the
-        <literal>ROLE</literal> clause, and the default inheritance when
-        adding this role as a member using the <literal>GRANT</literal>
-        statement.  In such <literal>GRANT</literal> statements, the
-        role's inheritance status will be used unless overridden by the
-        <literal>GRANT</literal> <literal>WITH INHERIT</literal> clause.
+        This controls whether a newly established membership of this role in
+        another has the <literal>INHERIT</literal> option.
+        Specifically, when this role is created with an <literal>IN ROLE</literal>
+        clause, is specified in the <literal>ROLE</literal> clause
+        of a future <command>CREATE ROLE</command> command, or when this
+        role is the "TO" role in a <command>GRANT</command> command
+        that does not specify <literal>INHERIT</literal> in the
+        <literal>WITH</literal> clause.
        </para>
 
        <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 without the inherit attribute.
-        Without role inheritance, the only other value of membership
-        is via <command>SET ROLE</command>, assuming the membership has
-        the <literal>SET</literal> attribute.
+        See "GRANT on Roles" on the <command>GRANT</command> reference page
+        for more information on what the <literal>INHERIT</literal> option
+        on a membership grant does.
+       </para>
+
+       <para>
+        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
+        the <command>GRANT</command> command 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.
@@ -293,9 +293,12 @@ 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 or to disallow <literal>SET ROLE</literal>; use a
-        separate <command>GRANT</command> command to do that.)
+        roles.  The new role will have the <literal>SET</literal> option
+        on the named role(s), and the <literal>INHERIT</literal> option
+        unless the <literal>NOINHERIT</literal> attribute has been specified for this role.
+        The new role will not have the <literal>ADMIN</literal> option.
+        See the <command>GRANT</command> command for modifying these options
+        after the new role is created.
        </para>
       </listitem>
      </varlistentry>
@@ -305,8 +308,11 @@ 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, of the new role.  Any named roles with
+        the <literal>INHERIT</literal> attribute will also have the <literal>INHERIT</literal>
+        option in the membership grant.
+        This in effect makes the new role a <quote>group</quote>.
        </para>
       </listitem>
      </varlistentry>
@@ -315,10 +321,9 @@ 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 behaves identical to the <literal>ROLE</literal> clause,
+        but the named roles are also added to the new role(s) with the <literal>ADMIN</literal> option,
+        giving them the right to grant membership in this role to others.
        </para>
       </listitem>
      </varlistentry>
@@ -361,15 +366,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>
@@ -469,8 +478,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <repl
   <para>
    The behavior specified by the SQL standard is most closely approximated
    by giving <literal>LOGIN</literal> roles
-   the <literal>NOINHERIT</literal> attribute, while
-   <literal>NOLOGIN</literal>roles are given the <literal>INHERIT</literal>
+   the <literal>NOINHERIT</literal> attribute, while giving
+   <literal>NOLOGIN</literal> roles the <literal>INHERIT</literal>
    attribute.
   </para>
 
-- 
2.34.1