doc: improve role option documentation

Role option management was changed in Postgres 16.  This patch improves
the docs around these changes, including CREATE ROLE's INHERIT option,
inheritance handling, and grant's ability to change role options.

Discussion: https://postgr.es/m/[email protected]

Co-authored-by: David G. Johnston
Backpatch-through: 16

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 7249fc74324d6d400000c3db22d51b7b7ba743ba..697cc514a5cb4ec4ae23e51c394ca96bc0cc6152 100644 (file)
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -68,6 +68,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.
+  
  
 
  
@@ -135,24 +146,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.
        
       
      
@@ -287,9 +295,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.
        
       
      
@@ -308,8 +317,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.
        
       
      
@@ -318,10 +331,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.
        
       
      
@@ -374,15 +387,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.
   
 
   
@@ -481,8 +498,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 1ae5770fbbf3203382ca71d1072bfe1927fee481..9d27b7fcde5695ecd18e0bed88ecebc0c9835b0f 100644 (file)
--- 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 92a299d2d33b6c3aa988ae78027d1f6db008d821..1f7d7e75ce9d69dfa3478ceb664cc7880ec16de4 100644 (file)
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -409,10 +409,10 @@ REVOKE group_role FROM role1
    than the original login role, and any database objects created are
    considered owned by the group role not the login role.  Second, member
    roles that have been granted membership with the
-   INHERIT 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;