Re: SET ROLE documentation not entirely correct

Joe Conway <[email protected]> Thu, 1 Aug 2019 14:48:30 -0400

Newsgroups	gmane.comp.db.postgresql.devel.documentation
Message-ID	<[email protected]>

On 4/27/19 4:02 PM, Joe Conway wrote:
> On 4/25/19 11:25 AM, Steven Winfield wrote:
>> Again, that's much clearer than what is currently there. It might help
>> if some of the language/definitions from pg_has_role() is used, though.
>> 
>> For example:
>> A role X is a "MEMBER" of another role Y if there is a chain of GRANTs
>> from X to Y via zero or more intermediate roles. This allows X to
>> execute "SET ROLE Y".
>> Additionally X has "USAGE" of Y if X and all the intermediate roles (but
>> *not* necessarily Y) are marked INHERIT. In this case X automatically
>> has the privileges of Y, without the need to "SET ROLE Y".
> 
> I've been whacking this around for the better part of the afternoon and
> came up with the attached. I think it is correct, and better than my
> previous proposal, but possibly need more polish. Comments welcome.


I've been sitting on this change a while and want to get it pushed.

Steven Winfield seemed happy with it -- any other comments before I
commit? Also this seems like it ought to be back-patched, but any
thoughts on that?

Thanks,

Joe

-- 
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development

set-role-docs-00.diff (text/x-patch, 3.2 KB)

diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index 0ef6eb9..d219a1e 100644
*** a/doc/src/sgml/ref/set_role.sgml
--- b/doc/src/sgml/ref/set_role.sgml
*************** RESET ROLE
*** 42,48 ****
  
    <para>
     The specified <replaceable class="parameter">role_name</replaceable>
!    must be a role that the current session user is a member of.
     (If the session user is a superuser, any role can be selected.)
    </para>
  
--- 42,48 ----
  
    <para>
     The specified <replaceable class="parameter">role_name</replaceable>
!    must be a role that the current session user is a <literal>MEMBER</literal> of.
     (If the session user is a superuser, any role can be selected.)
    </para>
  
*************** RESET ROLE
*** 63,78 ****
    <title>Notes</title>
  
    <para>
!    Using this command, it is possible to either add privileges or restrict
!    one's privileges.  If the session user role has the <literal>INHERITS</literal>
!    attribute, then it automatically has all the privileges of every role that
!    it could <command>SET ROLE</command> to; in this case <command>SET ROLE</command>
!    effectively drops all the privileges assigned directly to the session user
!    and to the other roles it is a member of, leaving only the privileges
!    available to the named role.  On the other hand, if the session user role
!    has the <literal>NOINHERITS</literal> attribute, <command>SET ROLE</command> drops the
!    privileges assigned directly to the session user and instead acquires the
!    privileges available to the named role.
    </para>
  
    <para>
--- 63,94 ----
    <title>Notes</title>
  
    <para>
!    Role "X" is a <literal>MEMBER</literal> of role "Y" if there is a chain of
!    grants between them. Additionally, role "X" has <literal>USAGE</literal>
!    of "Y", if "X", and all intermediate roles (but not necessarily "Y" itself),
!    are marked with the <literal>INHERIT</literal> attribute (which is the default).
!    See the <link linkend="functions-info"><function>pg_has_role()</function>
!    </link> for more information.
!   </para>
! 
!   <para>
!    Every role automatically has all the privileges it has been granted directly,
!    as well as that of every role with which it has <literal>USAGE</literal>.
!    However role attributes (as defined by <command>CREATE ROLE</command> or
!    <command>ALTER ROLE</command>) are not directly acquired from other roles.
!    Role attributes may only be gained via the <command>SET ROLE</command> command.
!   </para>
! 
!   <para>
!    The <command>SET ROLE</command> command drops all privileges assigned directly
!    to the session user and instead acquires the privileges available to the target
!    role, including any roles for which the target has <literal>USAGE</literal>.
!    The net effect is that the <command>SET ROLE</command> command may either add
!    privileges or restrict privileges. When the session role has
!    <literal>USAGE</literal> on the target role, the remaining privileges will be
!    equal to, or a subset of, the original privileges. On the other hand,
!    when the session role does not have <literal>USAGE</literal> on the target
!    role, the privileges may be completely different, and possibly expanded.
    </para>
  
    <para>

signature.asc (application/pgp-signature, 833 B)