Thread

[PATCH v3 07/11] Cleanup summary of role powers.

Karl O. Pinc <kop@karlpinc.com> — 2023-09-25T21:39:02Z

Make sentences shorter.  Explain privileges v.s. permissions.

This commit assumes that there is a distinction in the PostgreSQL
vocabulary between role privileges and permissions.  Privileges being
a specific Postgres term for powers granted to roles via GRANT.
Permissions being abilities to perform specific operations that comes
with privileges, but also with role attributes like CREATEDB.  So
permissions are a broader category than privileges, in terms of where
they come from.  As well as being a narrower category in another
sense, in that some privileges, like object ownership, carry with them
a swath of individual permissions/abilities, like USAGE.

It seems a useful distinction to make, in terms of thinking about how
object access works.  Essential in fact, since both privileges
(e.g. ownership) and role attributes (e.g. SUPERUSER) give roles
abilities, aka permissions (e.g. SELECT).  Without the distinction you
can't describe role inheritance (attributes don't, privileges do) or
discuss the source of particular access rights.  If access rights, aka
permissions, aka "abilities to do things", are the same as privileges
how come some privileges convey multiple abilities, abilities that
have their own names; how can you get an ability via a role attribute
but not have the privilege?  It seems most clear to, conceptually at
least, have a separate set of permissions (abilities) that come via
privileges granted to roles and role attributes assigned to roles.

So, I'm not sure my choice of vocabulary is perfect.  One might use
"rights" or some other word rather than "permissions".  But I think
that there should be a clear distinction between the 3 concepts of
granted privileges, role attributes, and permissions to perform
specific operations.

I also would argue that it is not necessary to scour the existing
documentation and patch to obtain perfect consistency in vocabulary
usage. The existing wording seems acceptable in practice and I don't
see anyone who's read what's already there to be confused by the
changes presented here.
---
 doc/src/sgml/user-manag.sgml | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 27c1f3d703..492325e8a2 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -7,11 +7,14 @@
   <productname>PostgreSQL</productname> manages database access permissions
   using the concept of <firstterm>roles</firstterm>.  A role can be thought of as
   either a database user, or a group of database users, depending on how
-  the role is set up.  Roles can own database objects (for example, tables
-  and functions) and can assign privileges on those objects to other roles to
-  control who has access to which objects.  Furthermore, it is possible
-  to grant <firstterm>membership</firstterm> in a role to another role, thus
-  allowing the member role to use privileges assigned to another role.
+  the role is set up.
+  Roles can own database objects (for example, tables and functions).
+  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.
+  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.
  </para>
 
  <para>
-- 
2.30.2


--MP_/.arW0LC=Yi8JO9BRih4YlyS
Content-Type: text/x-patch
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename=v3-0008-Explain-the-difference-between-role-attributes-an.patch