Improve documentation of the role-dropping process.

In general one may have to run both REASSIGN OWNED and DROP OWNED to get
rid of all the dependencies of a role to be dropped.  This was alluded to
in the REASSIGN OWNED man page, but not really spelled out in full; and in
any case the procedure ought to be documented in a more prominent place
than that.  Add a section to the "Database Roles" chapter explaining this,
and do a bit of wordsmithing in the relevant commands' man pages.

diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml
index 64906efd3dcfc3c253a42ba47805b79a7df52742..d03cc57845082bf2ddb02e7e7f00663efce38b12 100644 (file)
--- a/doc/src/sgml/ref/drop_owned.sgml
+++ b/doc/src/sgml/ref/drop_owned.sgml
@@ -90,19 +90,24 @@ DROP OWNED BY { name | CURRENT_USER
   
    The  command is an alternative that
    reassigns the ownership of all the database objects owned by one or
-   more roles.
+   more roles.  However, REASSIGN OWNED does not deal with
+   privileges for other objects.
   
 
   
    Databases and tablespaces owned by the role(s) will not be removed.
   
+
+  
+   See  for more discussion.
+  
  
 
  
   Compatibility
 
   
-   The DROP OWNED statement is a
+   The DROP OWNED command is a
    PostgreSQL extension.
   
  

diff --git a/doc/src/sgml/ref/drop_role.sgml b/doc/src/sgml/ref/drop_role.sgml
index 9a93da624a5ab8a8e1bbe1da5741729165502fb8..75b48f94f9ace8577d9c7eaed3f9f82e88307bd4 100644 (file)
--- a/doc/src/sgml/ref/drop_role.sgml
+++ b/doc/src/sgml/ref/drop_role.sgml
@@ -39,10 +39,10 @@ DROP ROLE [ IF EXISTS ] name [, ...
    A role cannot be removed if it is still referenced in any database
    of the cluster; an error will be raised if so.  Before dropping the role,
    you must drop all the objects it owns (or reassign their ownership)
-   and revoke any privileges the role has been granted. The 
-   linkend="sql-reassign-owned">
-   and ">
-   commands can be useful for this purpose.
+   and revoke any privileges the role has been granted on other objects.
+   The  and -owned">
+   commands can be useful for this purpose; see ">
+   for more discussion.
   
 
   

diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml
index 24e2a87ff2db5ea54cf7675569002cb68c6d8a69..38e5418d0787a6212cae76543d24d6ad224b5353 100644 (file)
--- a/doc/src/sgml/ref/drop_user.sgml
+++ b/doc/src/sgml/ref/drop_user.sgml
@@ -29,7 +29,7 @@ DROP USER [ IF EXISTS ] name [, ...
   Description
 
   
-   DROP USER is now an alias for
+   DROP USER is simply an alternate spelling of
    .
   
  

diff --git a/doc/src/sgml/ref/reassign_owned.sgml b/doc/src/sgml/ref/reassign_owned.sgml
index 382cba337bd491d7aa1f92fa7acb59d5b85f2bb9..ccd038629bf7f35e031a08e4106cc9824169a5b0 100644 (file)
--- a/doc/src/sgml/ref/reassign_owned.sgml
+++ b/doc/src/sgml/ref/reassign_owned.sgml
@@ -31,8 +31,9 @@ REASSIGN OWNED BY { old_role | CURR
 
   
    REASSIGN OWNED instructs the system to change
-   the ownership of database objects owned by one of the
-   old_roles, to new_role.
+   the ownership of database objects owned by any of the
+   old_roles to
+   new_role.
   
  
 
@@ -82,16 +83,18 @@ REASSIGN OWNED BY { old_role | CURR
 
   
    The  command is an alternative that
-   drops all the database objects owned by one or more roles. Note
-   also that DROP OWNED requires privileges only
-   on the source role(s).
+   simply drops all the database objects owned by one or more roles.
   
 
   
-   The REASSIGN OWNED command does not affect the
-   privileges granted to the old_roles in objects that are not owned
-   by them.  Use DROP OWNED to revoke those
-   privileges.
+   The REASSIGN OWNED command does not affect any
+   privileges granted to the old_roles for
+   objects that are not owned by them.  Use DROP OWNED to
+   revoke such privileges.
+  
+
+  
+   See  for more discussion.
   
 
  
@@ -100,7 +103,7 @@ REASSIGN OWNED BY { old_role | CURR
   Compatibility
 
   
-   The REASSIGN OWNED statement is a
+   The REASSIGN OWNED command is a
    PostgreSQL extension.
   
  

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 6476e3f9d8002b99fadd4c9bda9fec39ad6c2f63..1952cac6510291ba6a040446b868fcaa65b6957f 100644 (file)
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -7,8 +7,8 @@
   PostgreSQL manages database access permissions
   using the concept of roles.  A role can be thought of as
   either a database user, or a group of database users, depending on how
-  the role is set up.  Roles can own database objects (for example,
-  tables) and can assign privileges on those objects to other roles to
+  the role is set up.  Roles can own database objects (for example, tables
+  and functions) and can assign privileges on those objects to other roles to
   control who has access to which objects.  Furthermore, it is possible
   to grant membership in a role to another role, thus
   allowing the member role to use privileges assigned to another role.
@@ -213,7 +213,7 @@ CREATE USER name;
        
         A role must explicitly be given permission to initiate streaming
         replication (except for superusers, since those bypass all permission
-        checks). A role used for streaming replication must always
+        checks). A role used for streaming replication must
         have LOGIN permission as well. To create such a role, use
         CREATE ROLE name REPLICATION
         LOGIN.
@@ -408,9 +408,67 @@ RESET ROLE;
 DROP ROLE name;
 
    Any memberships in the group role are automatically revoked (but the
-   member roles are not otherwise affected).  Note however that any objects
-   owned by the group role must first be dropped or reassigned to other
-   owners; and any permissions granted to the group role must be revoked.
+   member roles are not otherwise affected).
+  
+ 
+
+ 
+  Dropping Roles
+
+  
+   Because roles can own database objects and can hold privileges
+   to access other objects, dropping a role is often not just a matter of a
+   quick .  Any objects owned by the role must
+   first be dropped or reassigned to other owners; and any permissions
+   granted to the role must be revoked.
+  
+
+  
+   Ownership of objects can be transferred one at a time
+   using ALTER commands, for example:
+
+ALTER TABLE bobs_table OWNER TO alice;
+
+   Alternatively, the  command can be
+   used to reassign ownership of all objects owned by the role-to-be-dropped
+   to a single other role.  Because REASSIGN OWNED can only
+   access objects in the current database, it is necessary to run it in each
+   database that contains objects owned by the role.
+  
+
+  
+   Once any valuable objects have been transferred to new owners, any
+   remaining objects owned by the role-to-be-dropped can be dropped with
+   the  command.  Again, this command can
+   only access objects in the current database, so it is necessary to run it
+   in each database that contains objects owned by the role.
+  
+
+  
+   DROP OWNED also takes care of removing any privileges granted
+   to the target role for objects that do not belong to it.
+   Because REASSIGN OWNED does not touch such objects, it's
+   typically necessary to run both REASSIGN OWNED
+   and DROP OWNED (in that order!) to fully remove the
+   dependencies of a role to be dropped.
+  
+
+  
+   In short then, the most general recipe for removing a role that has been
+   used to own objects is:
+
+  
+
+REASSIGN OWNED BY doomed_role TO successor_role;
+DROP OWNED BY doomed_role;
+-- repeat the above commands in each database of the cluster
+DROP ROLE doomed_role;
+
+
+  
+   If DROP ROLE is attempted while dependent objects still
+   remain, it will issue messages identifying which objects need to be
+   reassigned or dropped.