From d09293d321a614095cd1fa3fb949b18190c0130d Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <kop@karlpinc.com>
Date: Mon, 25 Sep 2023 17:18:58 -0500
Subject: [PATCH v6 08/15] Explain the difference between role attributes and
 role privileges

All of the information presented here is present elsewhere in the
documentation, but scattered about.  It is useful to have a summary;
one place where the interactions between INHERIT, the other role
attributes, and granting of privileges with roles is explained.
Otherwise, it is hard to synthesize this out of bits and pieces
mentioned elsewhere.
---
 doc/src/sgml/user-manag.sgml | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 492325e8a2..4a26ede8fb 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -12,9 +12,37 @@
   They can assign privileges on the owned objects, and thus the permissions
   the privileges carry, to other roles.
   Roles therefore control who has what access to which objects.
+ </para>
+
+ <indexterm>
+   <primary>role</primary>
+   <secondary>inheriting permissions</secondary>
+ </indexterm>
+
+ <indexterm>
+   <primary>role</primary>
+   <secondary>attributes</secondary>
+ </indexterm>
+
+ <indexterm>
+   <primary>role</primary>
+   <secondary>current role</secondary>
+ </indexterm>
+
+ <para>
   It is possible to grant <firstterm>membership</firstterm> in a role to
   another role, thus allowing the member role to use the privileges assigned
   to another role.
+  This acquisition of privilege can happen automatically, if the role given
+  membership has the <literal>INHERIT</literal> attribute, or manually, via
+  a <literal>SET ROLE</literal> to the granted role.
+  But it is important to distinguish between privileges, which are assigned
+  with <literal>GRANT</literal>, and role attributes,
+  like <literal>INHERIT</literal>, <literal>SUPERUSER</literal>, and
+  <literal>CREATEDB</literal>, which are assigned with <literal>CREATE
+  ROLE</literal> or <literal>ALTER ROLE</literal>.
+  Privileges may be inherited, role attributes cannot and are only effective
+  when <literal>SET ROLE</literal> changes the current role.
  </para>
 
  <para>
-- 
2.30.2