Doc: fix old oversights in GRANT/REVOKE documentation.

The GRANTED BY clause in GRANT/REVOKE ROLE has been there since 2005
but was never documented.  I'm not sure now whether that was just an
oversight or was intentional (given the limited capability of the
option).  But seeing that pg_dumpall does emit code that uses this
option, it seems like not documenting it at all is a bad idea.

Also, when we upgraded the syntax to allow CURRENT_USER/SESSION_USER
as the privilege recipient, the role form of GRANT was incorrectly
not modified to show that, and REVOKE's docs weren't touched at all.

Although I'm not that excited about GRANTED BY, the other oversight
seems serious enough to justify a back-patch.

Discussion: https://postgr.es/m/3070.1581526786@sss.pgh.pa.us

2 files changed, 49 insertions, 21 deletions

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 330fd79b219..9be13407736 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -79,14 +79,16 @@ GRANT { USAGE | ALL [ PRIVILEGES ] }
     ON TYPE <replaceable>type_name</replaceable> [, ...]
     TO <replaceable class="PARAMETER">role_specification</replaceable> [, ...] [ WITH GRANT OPTION ]
 
+GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
+    [ WITH ADMIN OPTION ]
+    [ GRANTED BY <replaceable class="PARAMETER">role_specification</replaceable> ]
+
 <phrase>where <replaceable class="PARAMETER">role_specification</replaceable> can be:</phrase>
 
     [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable>
   | PUBLIC
   | CURRENT_USER
   | SESSION_USER
-
-GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replaceable class="PARAMETER">role_name</replaceable> [, ...] [ WITH ADMIN OPTION ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -421,9 +423,16 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
   </para>
 
   <para>
+   If <literal>GRANTED BY</literal> is specified, the grant is recorded as
+   having been done by the specified role.  Only database superusers may
+   use this option, except when it names the same role executing the command.
+  </para>
+
+  <para>
    Unlike the case with privileges, membership in a role cannot be granted
-   to <literal>PUBLIC</>.  Note also that this form of the command does not
-   allow the noise word <literal>GROUP</>.
+   to <literal>PUBLIC</literal>.  Note also that this form of the command
+   does not allow the noise word <literal>GROUP</literal>
+   in <replaceable class="parameter">role_specification</replaceable>.
   </para>
  </refsect2>
  </refsect1>
@@ -654,6 +663,13 @@ GRANT admins TO joe;
    </para>
 
    <para>
+    The SQL standard allows the <literal>GRANTED BY</literal> option to
+    be used in all forms of <command>GRANT</command>.  PostgreSQL only
+    supports it when granting role membership, and even then only superusers
+    may use it in nontrivial ways.
+   </para>
+
+   <para>
     The SQL standard provides for a <literal>USAGE</literal> privilege
     on other kinds of objects: character sets, collations,
     translations.
diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml
index 13d5abac788..18e640accf0 100644
--- a/doc/src/sgml/ref/revoke.sgml
+++ b/doc/src/sgml/ref/revoke.sgml
@@ -26,14 +26,14 @@ REVOKE [ GRANT OPTION FOR ]
     [, ...] | ALL [ PRIVILEGES ] }
     ON { [ TABLE ] <replaceable class="PARAMETER">table_name</replaceable> [, ...]
          | ALL TABLES IN SCHEMA <replaceable>schema_name</replaceable> [, ...] }
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { SELECT | INSERT | UPDATE | REFERENCES } ( <replaceable class="PARAMETER">column_name</replaceable> [, ...] )
     [, ...] | ALL [ PRIVILEGES ] ( <replaceable class="PARAMETER">column_name</replaceable> [, ...] ) }
     ON [ TABLE ] <replaceable class="PARAMETER">table_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
@@ -41,73 +41,81 @@ REVOKE [ GRANT OPTION FOR ]
     [, ...] | ALL [ PRIVILEGES ] }
     ON { SEQUENCE <replaceable class="PARAMETER">sequence_name</replaceable> [, ...]
          | ALL SEQUENCES IN SCHEMA <replaceable>schema_name</replaceable> [, ...] }
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { CREATE | CONNECT | TEMPORARY | TEMP } [, ...] | ALL [ PRIVILEGES ] }
     ON DATABASE <replaceable>database_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON DOMAIN <replaceable>domain_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON FOREIGN DATA WRAPPER <replaceable>fdw_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON FOREIGN SERVER <replaceable>server_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { EXECUTE | ALL [ PRIVILEGES ] }
     ON { FUNCTION <replaceable>function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">arg_name</replaceable> ] <replaceable class="parameter">arg_type</replaceable> [, ...] ] ) ] [, ...]
          | ALL FUNCTIONS IN SCHEMA <replaceable>schema_name</replaceable> [, ...] }
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON LANGUAGE <replaceable>lang_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { SELECT | UPDATE } [, ...] | ALL [ PRIVILEGES ] }
     ON LARGE OBJECT <replaceable class="PARAMETER">loid</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
     ON SCHEMA <replaceable>schema_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { CREATE | ALL [ PRIVILEGES ] }
     ON TABLESPACE <replaceable>tablespace_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON TYPE <replaceable>type_name</replaceable> [, ...]
-    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ ADMIN OPTION FOR ]
-    <replaceable class="PARAMETER">role_name</replaceable> [, ...] FROM <replaceable class="PARAMETER">role_name</replaceable> [, ...]
+    <replaceable class="PARAMETER">role_name</replaceable> [, ...] FROM <replaceable class="PARAMETER">role_specification</replaceable> [, ...]
+    [ GRANTED BY <replaceable class="PARAMETER">role_specification</replaceable> ]
     [ CASCADE | RESTRICT ]
+
+<phrase>where <replaceable class="PARAMETER">role_specification</replaceable> can be:</phrase>
+
+    [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable>
+  | PUBLIC
+  | CURRENT_USER
+  | SESSION_USER
 </synopsis>
  </refsynopsisdiv>
 
@@ -167,10 +175,14 @@ REVOKE [ ADMIN OPTION FOR ]
   </para>
 
   <para>
-   When revoking membership in a role, <literal>GRANT OPTION</> is instead
-   called <literal>ADMIN OPTION</>, but the behavior is similar.
+   When revoking membership in a role, <literal>GRANT OPTION</literal> is instead
+   called <literal>ADMIN OPTION</literal>, but the behavior is similar.
+   This form of the command also allows a <literal>GRANTED BY</literal>
+   option, but that option is currently ignored (except for checking
+   the existence of the named role).
    Note also that this form of the command does not
-   allow the noise word <literal>GROUP</>.
+   allow the noise word <literal>GROUP</literal>
+   in <replaceable class="parameter">role_specification</replaceable>.
   </para>
  </refsect1>