From 63acfb79ab53d3833ad035728fb67a6c3018778f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 4 Dec 2015 14:44:13 -0500
Subject: [PATCH] Further improve documentation of the role-dropping process.

In commit 1ea0c73c2 I added a section to user-manag.sgml about how to drop
roles that own objects; but as pointed out by Stephen Frost, I neglected
that shared objects (databases or tablespaces) may need special treatment.
Fix that.  Back-patch to supported versions, like the previous patch.
---
 doc/src/sgml/user-manag.sgml | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 1952cac651..d1b6e5990d 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -431,17 +431,23 @@ ALTER TABLE bobs_table OWNER TO alice;
 </programlisting>
    Alternatively, the <xref linkend="sql-reassign-owned"> command can be
    used to reassign ownership of all objects owned by the role-to-be-dropped
-   to a single other role.  Because <command>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.
+   to a single other role.  Because <command>REASSIGN OWNED</> cannot access
+   objects in other databases, it is necessary to run it in each database
+   that contains objects owned by the role.  (Note that the first
+   such <command>REASSIGN OWNED</> will change the ownership of any
+   shared-across-databases objects, that is databases or tablespaces, that
+   are owned by the role-to-be-dropped.)
   </para>
 
   <para>
    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 <xref linkend="sql-drop-owned"> 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.
+   the <xref linkend="sql-drop-owned"> command.  Again, this command cannot
+   access objects in other databases, so it is necessary to run it in each
+   database that contains objects owned by the role.  Also, <command>DROP
+   OWNED</> will not drop entire databases or tablespaces, so it is
+   necessary to do that manually if the role owns any databases or
+   tablespaces that have not been transferred to new owners.
   </para>
 
   <para>
@@ -456,7 +462,6 @@ ALTER TABLE bobs_table OWNER TO alice;
   <para>
    In short then, the most general recipe for removing a role that has been
    used to own objects is:
-
   </para>
 <programlisting>
 REASSIGN OWNED BY doomed_role TO successor_role;
@@ -465,6 +470,12 @@ DROP OWNED BY doomed_role;
 DROP ROLE doomed_role;
 </programlisting>
 
+  <para>
+   When not all owned objects are to be transferred to the same successor
+   owner, it's best to handle the exceptions manually and then perform
+   the above steps to mop up.
+  </para>
+
   <para>
    If <command>DROP ROLE</> is attempted while dependent objects still
    remain, it will issue messages identifying which objects need to be