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

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index e98fe860528dadc72b4ed462e68bf0611293299f..bc573f7826b27ed5d245ecd33882313fbe026883 100644 (file)
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -79,14 +79,16 @@ GRANT { USAGE | ALL [ PRIVILEGES ] }
     ON TYPE type_name [, ...]
     TO role_specification [, ...] [ WITH GRANT OPTION ]
 
+GRANT role_name [, ...] TO role_specification [, ...]
+    [ WITH ADMIN OPTION ]
+    [ GRANTED BY role_specification ]
+
 where role_specification can be:
 
     [ GROUP ] role_name
   | PUBLIC
   | CURRENT_USER
   | SESSION_USER
-
-GRANT role_name [, ...] TO role_name [, ...] [ WITH ADMIN OPTION ]
 
  
 
@@ -236,10 +238,17 @@ GRANT role_name [, ...] TO 
    or revoke membership in any role that is not a superuser.
   
 
+  
+   If GRANTED BY 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.
+  
+
   
    Unlike the case with privileges, membership in a role cannot be granted
-   to PUBLIC.  Note also that this form of the command does not
-   allow the noise word GROUP.
+   to PUBLIC.  Note also that this form of the command
+   does not allow the noise word GROUP
+   in role_specification.
   
  
  
@@ -398,6 +407,13 @@ GRANT admins TO joe;
     to roles.
    
 
+   
+    The SQL standard allows the GRANTED BY option to
+    be used in all forms of GRANT.  PostgreSQL only
+    supports it when granting role membership, and even then only superusers
+    may use it in nontrivial ways.
+   
+
    
     The SQL standard provides for a USAGE privilege
     on other kinds of objects: character sets, collations,

diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml
index e96d45e7e31744b2f2f0e0fc3bf464209b3816dd..b6bac21c57a3a2c39f7d0f0a40167816cf31f8f2 100644 (file)
--- 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 ] table_name [, ...]
          | ALL TABLES IN SCHEMA schema_name [, ...] }
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { SELECT | INSERT | UPDATE | REFERENCES } ( column_name [, ...] )
     [, ...] | ALL [ PRIVILEGES ] ( column_name [, ...] ) }
     ON [ TABLE ] table_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
@@ -41,73 +41,81 @@ REVOKE [ GRANT OPTION FOR ]
     [, ...] | ALL [ PRIVILEGES ] }
     ON { SEQUENCE sequence_name [, ...]
          | ALL SEQUENCES IN SCHEMA schema_name [, ...] }
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { CREATE | CONNECT | TEMPORARY | TEMP } [, ...] | ALL [ PRIVILEGES ] }
     ON DATABASE database_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON DOMAIN domain_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON FOREIGN DATA WRAPPER fdw_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON FOREIGN SERVER server_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { EXECUTE | ALL [ PRIVILEGES ] }
     ON { { FUNCTION | PROCEDURE | ROUTINE } function_name [ ( [ [ argmode ] [ arg_name ] arg_type [, ...] ] ) ] [, ...]
          | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA schema_name [, ...] }
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON LANGUAGE lang_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { SELECT | UPDATE } [, ...] | ALL [ PRIVILEGES ] }
     ON LARGE OBJECT loid [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
     ON SCHEMA schema_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { CREATE | ALL [ PRIVILEGES ] }
     ON TABLESPACE tablespace_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ GRANT OPTION FOR ]
     { USAGE | ALL [ PRIVILEGES ] }
     ON TYPE type_name [, ...]
-    FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+    FROM role_specification [, ...]
     [ CASCADE | RESTRICT ]
 
 REVOKE [ ADMIN OPTION FOR ]
-    role_name [, ...] FROM role_name [, ...]
+    role_name [, ...] FROM role_specification [, ...]
+    [ GRANTED BY role_specification ]
     [ CASCADE | RESTRICT ]
+
+where role_specification can be:
+
+    [ GROUP ] role_name
+  | PUBLIC
+  | CURRENT_USER
+  | SESSION_USER
 
  
 
@@ -169,8 +177,12 @@ REVOKE [ ADMIN OPTION FOR ]
   
    When revoking membership in a role, GRANT OPTION is instead
    called ADMIN OPTION, but the behavior is similar.
+   This form of the command also allows a GRANTED BY
+   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 GROUP.
+   allow the noise word GROUP
+   in role_specification.