Basic documentation for ROLEs. The user-manag chapter still needs to

be rewritten, but at least the reference pages are reasonably sane.

doc/src/sgml/ref/grant.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.47 2005/05/26 20:05:03 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.48 2005/07/26 23:24:02 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -44,6 +44,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 GRANT { CREATE | ALL [ PRIVILEGES ] }
     ON TABLESPACE <replaceable>tablespacename</> [, ...]
     TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT <replaceable class="PARAMETER">role</replaceable> [, ...]
+    TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH ADMIN OPTION ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -51,20 +54,39 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
   <title>Description</title>
 
   <para>
-   The <command>GRANT</command> command gives specific privileges on
-   an object (table, view, sequence, database, function,
-   procedural language, schema, or tablespace) to
-   one or more users or groups of users.  These privileges are added
+   The <command>GRANT</command> command has two basic variants: one
+   that grants privileges on a database object (table, view, sequence,
+   database, function, procedural language, schema, or tablespace),
+   and one that grants membership in a role.  These variants are
+   similar in many ways, but they are different enough to be described
+   separately.
+  </para>
+
+  <para>
+   As of <productname>PostgreSQL</productname> 8.1, the concepts of users and
+   groups have been unified into a single kind of entity called a role.
+   It is therefore no longer necessary to use the keyword <literal>GROUP</>
+   to identify whether a grantee is a user or a group.  <literal>GROUP</>
+   is still allowed in the command, but it is a noise word.
+  </para>
+
+ <refsect2 id="sql-grant-description-objects">
+  <title>GRANT on Database Objects</title>
+
+  <para>
+   This variant of the <command>GRANT</command> command gives specific
+   privileges on a database object to
+   one or more roles.  These privileges are added
    to those already granted, if any.
   </para>
 
   <para>
    The key word <literal>PUBLIC</literal> indicates that the
-   privileges are to be granted to all users, including those that may
+   privileges are to be granted to all roles, including those that may
    be created later.  <literal>PUBLIC</literal> may be thought of as an
-   implicitly defined group that always includes all users.
-   Any particular user will have the sum
-   of privileges granted directly to him, privileges granted to any group he
+   implicitly defined group that always includes all roles.
+   Any particular role will have the sum
+   of privileges granted directly to it, privileges granted to any role it
    is presently a member of, and privileges granted to
    <literal>PUBLIC</literal>.
   </para>
@@ -72,9 +94,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
   <para>
    If <literal>WITH GRANT OPTION</literal> is specified, the recipient
    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>.
+   option, the recipient cannot do that.  Grant options cannot be granted
+   to <literal>PUBLIC</literal>.
   </para>
 
   <para>
@@ -258,6 +279,24 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
    The privileges required by other commands are listed on the
    reference page of the respective command.
   </para>
+ </refsect2>
+
+ <refsect2 id="sql-grant-description-roles">
+  <title>GRANT on Roles</title>
+
+  <para>
+   This variant of the <command>GRANT</command> command grants membership
+   in a role to one or more other roles.  Membership in a role is significant
+   because it conveys the privileges granted to a role to each of its
+   members.
+  </para>
+
+  <para>
+   If <literal>WITH ADMIN OPTION</literal> is specified, the member may
+   in turn grant membership in the role to others.  Without the admin
+   option, the recipient cannot do that.
+  </para>
+ </refsect2>
  </refsect1>
 
 
@@ -296,6 +335,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
     command, the command is performed as though it were issued by the
     owner of the affected object.  In particular, privileges granted via
     such a command will appear to have been granted by the object owner.
+    (For role membership, the membership appears to have been granted
+    by the containing role itself.)
    </para>
 
    <para>
@@ -392,6 +433,14 @@ GRANT ALL PRIVILEGES ON kinds TO manuel;
    else it will only grant those permissions for which the someone else has
    grant options.
   </para>
+
+  <para>
+   Grant membership in role <literal>admins</> to user <literal>joe</>:
+
+<programlisting>
+GRANT admins TO joe;
+</programlisting>
+  </para>
  </refsect1>
 
  <refsect1 id="sql-grant-compatibility">