diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 5aa5648ae7b..922686e5ced 100644
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -307,7 +307,7 @@ ALTER ROLE fred VALID UNTIL 'infinity';
- Give a role the ability to create other roles and new databases:
+ Give a role the ability to manage other roles and create new databases:
ALTER ROLE miriam CREATEROLE CREATEDB;
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index b6a4ea1f722..89df6dbf721 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -119,11 +119,11 @@ in sync when changing the above synopsis!
These clauses determine whether a role will be permitted to
- create new roles (that is, execute CREATE ROLE).
- A role with CREATEROLE privilege can also alter
- and drop other roles.
- If not specified,
- NOCREATEROLE is the default.
+ create, alter, drop, comment on, change the security label for,
+ and grant or revoke membership in other roles.
+ See for more details about what
+ capabilities are conferred by this privilege.
+ If not specified, NOCREATEROLE is the default.
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 17579e50afb..0e1a39a3fe6 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -41,10 +41,14 @@ PostgreSQL documentation
- If you wish to create a new superuser, you must connect as a
- superuser, not merely with CREATEROLE privilege.
+ If you wish to create a role with the SUPERUSER,
+ REPLICATION, or BYPASSRLS privilege,
+ you must connect as a superuser, not merely with
+ CREATEROLE privilege.
Being a superuser implies the ability to bypass all access permission
- checks within the database, so superuser access should not be granted lightly.
+ checks within the database, so superuser access should not be granted
+ lightly. CREATEROLE also conveys
+ very extensive privileges.
@@ -221,8 +225,12 @@ PostgreSQL documentation
- The new user will be allowed to create new roles (that is,
- this user will have CREATEROLE privilege).
+ The new user will be allowed to create, alter, drop, comment on,
+ change the security label for, and grant or revoke membership in
+ other roles; that is,
+ this user will have CREATEROLE privilege.
+ See for more details about what
+ capabilities are conferred by this privilege.
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 54cb253d95e..9af9c00a6c9 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -191,7 +191,7 @@ CREATE USER name;
- role creationroleprivilege to create
+ role creationroleprivilege to create
A role must be explicitly given permission to create more roles
@@ -200,9 +200,38 @@ CREATE USER name;
name CREATEROLE.
A role with CREATEROLE privilege can alter and drop
other roles, too, as well as grant or revoke membership in them.
- However, to create, alter, drop, or change membership of a
- superuser role, superuser status is required;
- CREATEROLE is insufficient for that.
+ Altering a role includes most changes that can be made using
+ ALTER ROLE, including, for example, changing
+ passwords. It also includes modifications to a role that can
+ be made using the COMMENT and
+ SECURITY LABEL commands.
+
+
+ However, CREATEROLE does not convey the ability to
+ create SUPERUSER roles, nor does it convey any
+ power over SUPERUSER roles that already exist.
+ Furthermore, CREATEROLE does not convey the power
+ to create REPLICATION users, nor the ability to
+ grant or revoke the REPLICATION privilege, nor the
+ ability to modify the role properties of such users. However, it does
+ allow ALTER ROLE ... SET and
+ ALTER ROLE ... RENAME to be used on
+ REPLICATION roles, as well as the use of
+ COMMENT ON ROLE,
+ SECURITY LABEL ON ROLE,
+ and DROP ROLE.
+ Finally, CREATEROLE does not
+ confer the ability to grant or revoke the BYPASSRLS
+ privilege.
+
+
+ Because the CREATEROLE privilege allows a user
+ to grant or revoke membership even in roles to which it does not (yet)
+ have any access, a CREATEROLE user can obtain access
+ to the capabilities of every predefined role in the system, including
+ highly privileged roles such as
+ pg_execute_server_program and
+ pg_write_server_files.
@@ -277,16 +306,6 @@ CREATE USER name;
and commands for details.
-
-
- It is good practice to create a role that has the CREATEDB
- and CREATEROLE privileges, but is not a superuser, and then
- use this role for all routine management of databases and roles. This
- approach avoids the dangers of operating as a superuser for tasks that
- do not really require it.
-
-
-
A role can also have role-specific defaults for many of the run-time
configuration settings described in