diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index 8dd2a6395c..f2dc841b85 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -133,24 +133,33 @@ 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. + + + + Role membership with the inherit attribute can automatically use + whatever database privileges have been granted to all roles it + is directly or indirectly a member of, though the chain stops + at memberships lacking the inherit attribute. Without role + inheritance, the only other value of membership is the use of + SET ROLE, assuming the membership chain has + SET attributes. 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. It could not be specified + during role addition with GRANT, and changing + this role-level property would also change the inheritance behavior + of all existing memberships. This is no longer the case. @@ -285,9 +294,13 @@ 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 attribute is specified. See the command, which has additional attribute + control during membership creation and to modify these options + after the new role is created. @@ -297,8 +310,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 INHERIT attributes will have + INHERIT enabled in the new membership. New + memberships will have the ADMIN option disabled. @@ -307,10 +324,10 @@ in sync when changing the above synopsis! ADMIN role_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 is similar to + ROLE, but the named roles are added as members + of the new role with ADMIN enabled, giving + them the right to grant membership in this role to others. @@ -353,15 +370,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. @@ -459,9 +480,11 @@ 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. + The behavior specified by the SQL standard is most closely approximated + creating SQL-standard users as PostgreSQL + roles with the NOINHERIT attribute, and SQL-standard + roles as PostgreSQL roles with the + INHERIT attribute. diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 1ae5770fbb..fbf98b0cad 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -249,11 +249,14 @@ 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 attributes. 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 attributes of + an existing membership, simply specify the membership with updated + attribute values. @@ -275,15 +278,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, it defaults to the inheritance status of the role + being added.