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 1952cac6510..d1b6e5990db 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
--
GitLab