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! 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 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;