From 1ea0c73c2b112911fb2ef297121be92d3b0ca35e Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 7 Oct 2015 16:12:05 -0400 Subject: [PATCH] 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. --- doc/src/sgml/ref/drop_owned.sgml | 9 +++- doc/src/sgml/ref/drop_role.sgml | 8 ++-- doc/src/sgml/ref/drop_user.sgml | 2 +- doc/src/sgml/ref/reassign_owned.sgml | 23 +++++---- doc/src/sgml/user-manag.sgml | 70 +++++++++++++++++++++++++--- 5 files changed, 89 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml index 64906efd3d..d03cc57845 100644 --- 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 9a93da624a..75b48f94f9 100644 --- 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 - and - commands can be useful for this purpose. + and revoke any privileges the role has been granted on other objects. + The and + 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 24e2a87ff2..38e5418d07 100644 --- 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 382cba337b..ccd038629b 100644 --- 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 6476e3f9d8..1952cac651 100644 --- 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.