diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 8dd2a6395c..f3b89e7239 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -66,6 +66,17 @@ in sync when changing the above synopsis!
Note that roles are defined at the database cluster
level, and so are valid in all databases in the cluster.
+
+
+ During role creation it is possible to immediately assign the newly created
+ role to be a member of an existing role, and also assign existing roles
+ to be members of the newly created role. The rules for which initial
+ role membership options are enabled described below in the
+ IN ROLE, ROLE, and
+ ADMIN clauses. The
+ command has fine-grained option control during membership creation,
+ and the ability to modify these options after the new role is created.
+
@@ -133,24 +144,21 @@ in sync when changing the above synopsis!
NOINHERIT
- When the GRANT statement is used to confer
- membership in one role to another role, the GRANT
- may use the WITH INHERIT clause to specify whether
- the privileges of the granted role should be inherited
- by the new member. If the GRANT statement does not
- specify either inheritance behavior, the new GRANT
- will be created WITH INHERIT TRUE if the member
- role is set to INHERIT and to
- WITH INHERIT FALSE if it is set to
- NOINHERIT.
+ This affects the membership inheritance status when this
+ role is added as a member of another role, both in this and
+ future commands. Specifically, it controls the inheritance
+ status of memberships added with this command using the
+ IN ROLE clause, and in later commands using
+ the ROLE clause. It is also used as the
+ default inheritance status when adding this role as a member
+ using the GRANT command. If not specified,
+ INHERIT is the default.
In PostgreSQL versions before 16,
- the GRANT statement did not support
- WITH INHERIT. Therefore, changing this role-level
- property would also change the behavior of already-existing grants.
- This is no longer the case.
+ inheritance was a role-level attribute that controlled all runtime
+ membership checks for that role.
@@ -285,9 +293,10 @@ in sync when changing the above synopsis!
The IN ROLE clause causes the new role to
be automatically added as a member of the specified existing
- roles. (Note that there is no option to add the new role as an
- administrator; use a separate GRANT command
- to do that.)
+ roles. The new membership will have the SET
+ option enabled and the ADMIN option disabled.
+ The INHERIT option will be enabled unless the
+ NOINHERIT option is specified.
@@ -297,8 +306,12 @@ in sync when changing the above synopsis!
The ROLE clause causes one or more specified
- existing roles to be automatically added as members of the new
- role. This in effect makes the new role a group.
+ existing roles to be automatically added as members, with the
+ SET option enabled. This in effect makes the
+ new role a group. Roles named in this clause
+ with role-level the INHERIT attribute will have
+ the INHERIT option enabled in the new membership.
+ New memberships will have the ADMIN option disabled.
@@ -307,10 +320,10 @@ in sync when changing the above synopsis!
ADMINrole_name
- The ADMIN clause is like ROLE,
- but the named roles are added to the new role WITH ADMIN
- OPTION, giving them the right to grant membership in this role
- to others.
+ The ADMIN clause has the same effect as
+ ROLE, but the named roles are added as members
+ of the new role with ADMIN enabled, giving
+ them the right to grant membership in the new role to others.
@@ -353,15 +366,19 @@ in sync when changing the above synopsis!
- The INHERIT attribute governs inheritance of grantable
- privileges (that is, access privileges for database objects and role
- memberships). It does not apply to the special role attributes set by
- CREATE ROLE and ALTER ROLE. For example, being
- a member of a role with CREATEDB privilege does not immediately
- grant the ability to create databases, even if INHERIT is set;
- it would be necessary to become that role via
- SET ROLE before
- creating a database.
+ The role attributes defined here are non-inheritable, i.e., being a
+ member of a role with, e.g., CREATEDB will not
+ allow the member to create new databases even if the membership grant
+ has the INHERIT option. Of course, if the membership
+ grant has the SET option the member role would be able to
+ SET ROLE to the
+ createdb role and then create a new database.
+
+
+
+ The membership grants created by the
+ IN ROLE, ROLE, and ADMIN
+ clauses have the role executing this command as the grantee.
@@ -460,8 +477,10 @@ CREATE ROLE name [ WITH ADMIN
The behavior specified by the SQL standard is most closely approximated
- by giving users the NOINHERIT attribute, while roles are
- given the INHERIT attribute.
+ creating SQL-standard users as PostgreSQL
+ roles with the NOINHERIT option, and SQL-standard
+ roles as PostgreSQL roles with the
+ INHERIT option.
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 1ae5770fbb..9d27b7fcde 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -249,11 +249,16 @@ GRANT role_name [, ...] TO
This variant of the GRANT command grants membership
- in a role to one or more other roles. Membership in a role is significant
+ in a role to one or more other roles, and the modification of
+ membership options SET, INHERIT,
+ and ADMIN; see
+ for details. Membership in a role is significant
because it potentially allows access to the privileges granted to a role
to each of its members, and potentially also the ability to make changes
to the role itself. However, the actual permissions conferred depend on
- the options associated with the grant.
+ the options associated with the grant. To modify that options of
+ an existing membership, simply specify the membership with updated
+ option values.
@@ -261,7 +266,9 @@ GRANT role_name [, ...] TO TRUE or FALSE. The keyword
OPTION is accepted as a synonym for
TRUE, so that WITH ADMIN OPTION
- is a synonym for WITH ADMIN TRUE.
+ is a synonym for WITH ADMIN TRUE. When altering
+ an existing membership the omission of an option results in the current
+ value being retained.
@@ -275,15 +282,13 @@ GRANT role_name [, ...] TO
- The INHERIT option, if it is set to
- TRUE, causes the member to inherit the privileges of
- the granted role. That is, it can automatically use whatever database
- privileges have been granted to that role. If set to
- FALSE, the member does not inherit the privileges
- of the granted role. If this clause is not specified, it defaults to
- true if the member role is set to INHERIT and to false
- if the member role is set to NOINHERIT.
- See CREATE ROLE.
+ The INHERIT option controls the inheritance status
+ of the new membership; see for
+ details on inheritance. If it is set to TRUE,
+ it causes the new member to inherit from the granted role. If
+ set to FALSE, the new member does not inherit.
+ If unspecified when create a new role membership this defaults to
+ the inheritance attribute of the role being added.
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 1c011ac62b..e026a4e271 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -409,10 +409,10 @@ REVOKE group_role FROM role1INHERIT option automatically have use
- of the privileges of those roles, including any
- privileges inherited by those roles.
- As an example, suppose we have done:
+ INHERIT option automatically have use of the
+ privileges of those directly or indirectly a member of, though the
+ chain stops at memberships lacking the inherit option. As an example,
+ suppose we have done:
CREATE ROLE joe LOGIN;
CREATE ROLE admin;