From 412734767a7bf7faf8b777c157f0b7c2bb37f179 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 13 Oct 2005 23:26:00 +0000
Subject: [PATCH] Improve documentation about CREATEROLE privilege.

---
 doc/src/sgml/ref/grant.sgml  | 10 +++++++---
 doc/src/sgml/user-manag.sgml | 19 +++++++++++++++----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 57af287dc9c..8e8196f480d 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.48 2005/07/26 23:24:02 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.49 2005/10/13 23:26:00 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -293,8 +293,12 @@ GRANT <replaceable class="PARAMETER">role</replaceable> [, ...]
 
   <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.
+   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.  However,
+   database superusers can grant or revoke membership in any role to anyone.
+   Roles having <literal>CREATEROLE</> privilege can grant or revoke
+   membership in any role that is not a superuser.
   </para>
  </refsect2>
  </refsect1>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index f42666b8198..fea93aec915 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.30 2005/08/14 23:35:37 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.31 2005/10/13 23:26:00 tgl Exp $
 -->
 
 <chapter id="user-manag">
@@ -203,9 +203,10 @@ CREATE USER <replaceable>name</replaceable>;
         checks). To create such a role, use <literal>CREATE ROLE
         <replaceable>name</replaceable> CREATEROLE</literal>.
         A role with <literal>CREATEROLE</> privilege can alter and drop
-        other roles, too.  However, to alter or drop a superuser role,
-        superuser status is required; <literal>CREATEROLE</> is not sufficient
-        for that.
+        other roles, too, as well as grant or revoke membership in them.
+        However, to create, alter, drop, or change membership of a
+        superuser role, superuser status is required;
+        <literal>CREATEROLE</> is not sufficient for that.
        </para>
       </listitem>
      </varlistentry>
@@ -234,6 +235,16 @@ CREATE USER <replaceable>name</replaceable>;
     endterm="sql-alterrole-title"> commands for details.
    </para>
 
+  <tip>
+   <para>
+    It is good practice to create a role that has the <literal>CREATEDB</>
+    and <literal>CREATEROLE</> privileges, but is not a superuser, and then
+    use this role for all routine management of databases and roles.  This
+    approach avoids the dangers of operating as a superuser for tasks that
+    do not really require it.
+   </para>
+  </tip>
+
   <para>
    A role can also have role-specific defaults for many of the run-time
    configuration settings described in <xref