Align GRANT/REVOKE behavior more closely with the SQL spec, per discussion

of bug report #1150.  Also, arrange that the object owner's irrevocable
grant-option permissions are handled implicitly by the system rather than
being listed in the ACL as self-granted rights (which was wrong anyway).
I did not take the further step of showing these permissions in an
explicit 'granted by _SYSTEM' ACL entry, as that seemed more likely to
bollix up existing clients than to do anything really useful.  It's still
a possible future direction, though.

Author: tglsfdc

doc/src/sgml/ref/grant.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.39 2004/03/22 03:38:24 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.40 2004/06/01 21:49:21 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -67,9 +67,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 
   <para>
    If <literal>WITH GRANT OPTION</literal> is specified, the recipient
-   of the privilege may in turn grant it to others.  By default this
-   is not allowed.  Grant options can only be granted to individual
-   users, not to groups or <literal>PUBLIC</literal>.
+   of the privilege may in turn grant it to others.  Without a grant
+   option, the recipient cannot do that.  At present, grant options can
+   only be granted to individual users, not to groups or
+   <literal>PUBLIC</literal>.
   </para>
 
   <para>
@@ -79,8 +80,8 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
    however, choose to revoke some of his own privileges for safety.)
    The right to drop an object, or to alter its definition in any way is
    not described by a grantable privilege; it is inherent in the owner,
-   and cannot be granted or revoked.  It is not possible for the owner's
-   grant options to be revoked, either.
+   and cannot be granted or revoked.  The owner implicitly has all grant
+   options for the object, too.
   </para>
 
   <para>
@@ -150,7 +151,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>RULE</term>
      <listitem>
       <para>
-       Allows the creation of a rule on the table/view.  (See <xref
+       Allows the creation of a rule on the table/view.  (See the <xref
        linkend="sql-createrule" endterm="sql-createrule-title"> statement.)
       </para>
      </listitem>
@@ -171,7 +172,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>TRIGGER</term>
      <listitem>
       <para>
-       Allows the creation of a trigger on the specified table.  (See
+       Allows the creation of a trigger on the specified table.  (See the
        <xref linkend="sql-createtrigger" endterm="sql-createtrigger-title"> statement.)
       </para>
      </listitem>
@@ -234,7 +235,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>ALL PRIVILEGES</term>
      <listitem>
       <para>
-       Grant all of the privileges applicable to the object at once.
+       Grant all of the available privileges at once.
        The <literal>PRIVILEGES</literal> key word is optional in
        <productname>PostgreSQL</productname>, though it is required by
        strict SQL.
@@ -257,6 +258,20 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
     to revoke access privileges.
    </para>
 
+   <para>
+    When a non-owner of an object attempts to <command>GRANT</> privileges
+    on the object, the command will fail outright if the user has no
+    privileges whatsoever on the object.  As long as some privilege is
+    available, the command will proceed, but it will grant only those
+    privileges for which the user has grant options.  The <command>GRANT ALL
+    PRIVILEGES</> forms will issue a warning message if no grant options are
+    held, while the other forms will issue a warning if grant options for
+    any of the privileges specifically named in the command are not held.
+    (In principle these statements apply to the object owner as well, but
+    since the owner is always treated as holding all grant options, the
+    cases can never occur.)
+   </para>
+
    <para>
     It should be noted that database superusers can access
     all objects regardless of object privilege settings.  This
@@ -273,10 +288,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
    </para>
 
    <para>
-    Currently, to grant privileges in <productname>PostgreSQL</productname>
-    to only a few columns, you must
-    create a view having the desired columns and then grant privileges
-    to that view.
+    Currently, <productname>PostgreSQL</productname> does not support
+    granting or revoking privileges for individual columns of a table.
+    One possible workaround is to create a view having just the desired
+    columns and then grant privileges to that view.
    </para>
 
    <para>
@@ -286,9 +301,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 => \z mytable
 
                         Access privileges for database "lusitania"
- Schema |  Name   | Type  |          Access privileges
---------+---------+-------+-----------------------------------------------------------------
- public | mytable | table | {=r/postgres,miriam=arwdRxt/postgres,"group todos=arw/postgres"}
+ Schema |  Name   | Type  |                     Access privileges
+--------+---------+-------+------------------------------------------------------------
+ public | mytable | table | {miriam=arwdRxt/miriam,=r/miriam,"group todos=arw/miriam"}
 (1 row)
 </programlisting>
     The entries shown by <command>\z</command> are interpreted thus:
@@ -331,7 +346,14 @@ and may include some privileges for <literal>PUBLIC</> depending on the
 object type, as explained above.  The first <command>GRANT</> or
 <command>REVOKE</> on an object
 will instantiate the default privileges (producing, for example,
-<literal>{=,miriam=arwdRxt}</>) and then modify them per the specified request.
+<literal>{miriam=arwdRxt/miriam}</>) and then modify them per the
+specified request.
+   </para>
+
+   <para>
+    Notice that the owner's implicit grant options are not marked in the
+    access privileges display.  A <literal>*</> will appear only when
+    grant options have been explicitly granted to someone.
    </para>
  </refsect1>
 
@@ -347,11 +369,17 @@ GRANT INSERT ON films TO PUBLIC;
   </para>
 
   <para>
-   Grant all privileges to user <literal>manuel</literal> on view <literal>kinds</literal>:
+   Grant all available privileges to user <literal>manuel</literal> on view
+   <literal>kinds</literal>:
 
 <programlisting>
 GRANT ALL PRIVILEGES ON kinds TO manuel;
 </programlisting>
+
+   Note that while the above will indeed grant all privileges if executed by a
+   superuser or the owner of <literal>kinds</literal>, when executed by someone
+   else it will only grant those permissions for which the someone else has
+   grant options.
   </para>
  </refsect1>
 

doc/src/sgml/ref/revoke.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.29 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.30 2004/06/01 21:49:21 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -81,6 +81,7 @@ REVOKE [ GRANT OPTION FOR ]
   <para>
    If <literal>GRANT OPTION FOR</literal> is specified, only the grant
    option for the privilege is revoked, not the privilege itself.
+   Otherwise, both the privilege and the grant option are revoked.
   </para>
 
   <para>
@@ -103,7 +104,7 @@ REVOKE [ GRANT OPTION FOR ]
 
   <para>
    Use <xref linkend="app-psql">'s <command>\z</command> command to
-   display the privileges granted on existing objects.  See also <xref
+   display the privileges granted on existing objects.  See <xref
    linkend="sql-grant" endterm="sql-grant-title"> for information about the format.
   </para>
 
@@ -114,9 +115,25 @@ REVOKE [ GRANT OPTION FOR ]
    C, then user A cannot revoke the privilege directly from C.
    Instead, user A could revoke the grant option from user B and use
    the <literal>CASCADE</literal> option so that the privilege is
-   automatically revoked from user C.
+   in turn revoked from user C.  For another example, if both A and B
+   have granted the same privilege to C, A can revoke his own grant
+   but not B's grant, so C will still effectively have the privilege.
   </para>
 
+   <para>
+    When a non-owner of an object attempts to <command>REVOKE</> privileges
+    on the object, the command will fail outright if the user has no
+    privileges whatsoever on the object.  As long as some privilege is
+    available, the command will proceed, but it will revoke only those
+    privileges for which the user has grant options.  The <command>REVOKE ALL
+    PRIVILEGES</> forms will issue a warning message if no grant options are
+    held, while the other forms will issue a warning if grant options for
+    any of the privileges specifically named in the command are not held.
+    (In principle these statements apply to the object owner as well, but
+    since the owner is always treated as holding all grant options, the
+    cases can never occur.)
+   </para>
+
    <para>
     If a superuser chooses to issue a <command>GRANT</> or <command>REVOKE</>
     command, the command is performed as though it were issued by the
@@ -140,11 +157,15 @@ REVOKE INSERT ON films FROM PUBLIC;
   </para>
 
   <para>
-   Revoke all privileges from user <literal>manuel</literal> on view <literal>kinds</literal>:
+   Revoke all privileges from user <literal>manuel</literal> on view
+   <literal>kinds</literal>:
 
-<programlisting>  
+<programlisting>
 REVOKE ALL PRIVILEGES ON kinds FROM manuel;
 </programlisting>
+
+   Note that this actually means <quote>revoke all privileges that I
+   granted</>.
   </para>
  </refsect1>