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 48cf0fa535bf25a5d4bc087f1de2b23d9581104f..0f34f6174f93ed54f964ad65768948e562ca43b1 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 [, ...] [ CASCAD
   
    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 92c0fb863dd3748f00a26cbbc78c698758b1b0a9..69263442ccd16f731ba0188ce31ea235c8c82093 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 1bdf03c51560a2987683f45a8b263701ea2bfa47..a4dd548bd17536ed697ec0ad7944cc21af17b4c8 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 0d6b1787e29da459f15d7d89a20dd3a405f58799..409cd673c38e86e9427fc447283817c79f1c185c 100644 (file)
--- a/doc/src/sgml/ref/reassign_owned.sgml
+++ b/doc/src/sgml/ref/reassign_owned.sgml
@@ -30,8 +30,9 @@ REASSIGN OWNED BY old_role [, ...]
 
   
    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.
   
  
 
@@ -81,16 +82,18 @@ REASSIGN OWNED BY old_role [, ...]
 
   
    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.
   
 
  
@@ -99,7 +102,7 @@ REASSIGN OWNED BY old_role [, ...]
   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 177ac7aa8c503883935ea08b8cdad272fe499ab6..4fce70060bc304ad890f299dfe3512907bf5afc6 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.