Allow grant-level control of role inheritance behavior.

The GRANT statement can now specify WITH INHERIT TRUE or WITH
INHERIT FALSE to control whether the member inherits the granted
role's permissions. For symmetry, you can now likewise write
WITH ADMIN TRUE or WITH ADMIN FALSE to turn ADMIN OPTION on or off.

If a GRANT does not specify WITH INHERIT, the behavior based on
whether the member role is marked INHERIT or NOINHERIT. This means
that if all roles are marked INHERIT or NOINHERIT before any role
grants are performed, the behavior is identical to what we had before;
otherwise, it's different, because ALTER ROLE [NO]INHERIT now only
changes the default behavior of future grants, and has no effect on
existing ones.

Patch by me. Reviewed and testing by Nathan Bossart and Tushar Ahuja,
with design-level comments from various others.

Discussion: http://postgr.es/m/CA+Tgmoa5Sf4PiWrfxA=sGzDKg0Ojo3dADw=wAHOhR9dggV=RmQ@mail.gmail.com

Author: robertmhaas

doc/src/sgml/catalogs.sgml

@@ -1717,6 +1717,16 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        <structfield>roleid</structfield> to others
       </para></entry>
      </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>inherit_option</structfield> <type>bool</type>
+      </para>
+      <para>
+       True if the member automatically inherits the privileges of the
+       granted role
+      </para></entry>
+     </row>
     </tbody>
    </tgroup>
   </table>

doc/src/sgml/ref/create_role.sgml

@@ -133,17 +133,24 @@ in sync when changing the above synopsis!
       <term><literal>NOINHERIT</literal></term>
       <listitem>
        <para>
-        These clauses determine whether a role <quote>inherits</quote> the
-        privileges of roles it is a member of.
-        A role with the <literal>INHERIT</literal> attribute can automatically
-        use whatever database privileges have been granted to all roles
-        it is directly or indirectly a member of.
-        Without <literal>INHERIT</literal>, membership in another role
-        only grants the ability to <command>SET ROLE</command> to that other role;
-        the privileges of the other role are only available after having
-        done so.
-        If not specified,
-        <literal>INHERIT</literal> is the default.
+        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>.
+       </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.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/grant.sgml

@@ -98,7 +98,7 @@ GRANT { USAGE | ALL [ PRIVILEGES ] }
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
 
 GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replaceable class="parameter">role_specification</replaceable> [, ...]
-    [ WITH ADMIN OPTION ]
+    [ WITH { ADMIN | INHERIT } { OPTION | TRUE | FALSE } ]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
 
 <phrase>where <replaceable class="parameter">role_specification</replaceable> can be:</phrase>
@@ -255,7 +255,17 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
   </para>
 
   <para>
-   If <literal>WITH ADMIN OPTION</literal> is specified, the member can
+   The effect of membership in a role can be modified by specifying the
+   <literal>ADMIN</literal> or <literal>INHERIT</literal> option, each
+   of which can be set to either <literal>TRUE</literal> or
+   <literal>FALSE</literal>. The keyword <literal>OPTION</literal> is accepted
+   as a synonym for <literal>TRUE</literal>, so that
+   <literal>WITH ADMIN OPTION</literal>
+   is a synonym for <literal>WITH ADMIN TRUE</literal>.
+  </para>
+
+  <para>
+   The <literal>ADMIN</literal> option allows the member to
    in turn grant membership in the role to others, and revoke membership
    in the role as well.  Without the admin option, ordinary users cannot
    do that.  A role is not considered to hold <literal>WITH ADMIN
@@ -265,6 +275,18 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    in any role that is not a superuser.
   </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>.
+  </para>
+
   <para>
    If <literal>GRANTED BY</literal> is specified, the grant is recorded as
    having been done by the specified role. A user can only attribute a grant

doc/src/sgml/ref/revoke.sgml

@@ -125,7 +125,7 @@ REVOKE [ GRANT OPTION FOR ]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
     [ CASCADE | RESTRICT ]
 
-REVOKE [ ADMIN OPTION FOR ]
+REVOKE [ { ADMIN | INHERIT } OPTION FOR ]
     <replaceable class="parameter">role_name</replaceable> [, ...] FROM <replaceable class="parameter">role_specification</replaceable> [, ...]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
     [ CASCADE | RESTRICT ]
@@ -206,6 +206,13 @@ REVOKE [ ADMIN OPTION FOR ]
    allow the noise word <literal>GROUP</literal>
    in <replaceable class="parameter">role_specification</replaceable>.
   </para>
+
+  <para>
+   Just as <literal>ADMIN OPTION</literal> can be removed from an existing
+   role grant, it is also possible to revoke <literal>INHERIT OPTION</literal>.
+   This is equivalent to setting the value of that option to
+   <literal>FALSE</literal>.
+  </para>
  </refsect1>
 
  <refsect1 id="sql-revoke-notes">