On Wed, Jan 17, 2024 at 9:38 AM Bruce Momjian <br...@momjian.us> wrote:
> On Wed, Jan 17, 2024 at 09:28:38AM +0100, Laurenz Albe wrote:
> > On Tue, 2024-01-16 at 17:03 -0500, Bruce Momjian wrote:
> > > I am unhappy with the documentation adjustments made to CREATE ROLE in
> > > Postgres 16 by this commit:
> > >
> > > commit e3ce2de09d
> > >
> > > I have attached a patch to re-add this information, and clarify it. I
> > > would like to apply this to PG 16 and master.
> >
> > I had to read the text twice before I understood it, but I cannot think
> > of a simpler way to write it.
>
> Yeah, I had the same feeling. A bullet list would be nice but overkill
> for a manual page.
>
>
I had a go at this.
I went with a more "bullet item" approach with my wording for
INHERIT/NOINHERIT.
The entire paragraph regarding how the INHERIT "option" works, as opposed
to the attribute, seems out of place where it was and the material is
already covered in the GRANT page. We should either improve that page or
extract this level of detail somewhere else, not try to clutter up the
CREATE ROLE page with it.
We consistently say what the default is for these attribute pairs, do so
here as well.
Turn the parenthetical in the IN ROLE section into actual assertive
documentation of what the clause does. Tweak ROLE and ADMIN as well to fit
in better.
Reword the discussion regarding non-inheritance to be more direct.
I added mention of the grantee aspect of privileges as a soft way of
further pointing out that the IN ROLE, ROLE, ADMIN clauses are limited in
what they can control in the resulting membership grants.
I choose to use the phrasing "giving ... roles" for both parts of the
sentence instead of switching to "... roles are given" for the second
half. More of a style choice but I didn't think switching really added
much and just makes it a bit wordier and possibly a bit more effort to
mentally parse.
Patch built on top of Bruce's role.diff, not HEAD
David J.
From ce4605354f1360662ffed6f0e239b2e06d107a85 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Wed, 17 Jan 2024 14:19:54 -0700
Subject: [PATCH] v2
---
doc/src/sgml/ref/create_role.sgml | 81 +++++++++++++++++--------------
1 file changed, 45 insertions(+), 36 deletions(-)
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 5c2b71bf69..f134feea27 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -133,29 +133,29 @@ in sync when changing the above synopsis!
<term><literal>NOINHERIT</literal></term>
<listitem>
<para>
- This controls the membership inheritance status when a new role
- is added as a member using the <literal>IN ROLE</literal> clause,
- when this role is later added as a member of a new role with the
- <literal>ROLE</literal> clause, and the default inheritance when
- adding this role as a member using the <literal>GRANT</literal>
- statement. In such <literal>GRANT</literal> statements, the
- role's inheritance status will be used unless overridden by the
- <literal>GRANT</literal> <literal>WITH INHERIT</literal> clause.
+ This controls whether a newly established membership of this role in
+ another has the <literal>INHERIT</literal> option.
+ Specifically, when this role is created with an <literal>IN ROLE</literal>
+ clause, is specified in the <literal>ROLE</literal> clause
+ of a future <command>CREATE ROLE</command> command, or when this
+ role is the "TO" role in a <command>GRANT</command> command
+ that does not specify <literal>INHERIT</literal> in the
+ <literal>WITH</literal> clause.
</para>
<para>
- Role membership with the inherit attribute can automatically
- use whatever database privileges have been granted to all
- roles it is directly or indirectly a member of, though the
- chain stops at memberships without the inherit attribute.
- Without role inheritance, the only other value of membership
- is via <command>SET ROLE</command>, assuming the membership has
- the <literal>SET</literal> attribute.
+ See "GRANT on Roles" on the <command>GRANT</command> reference page
+ for more information on what the <literal>INHERIT</literal> option
+ on a membership grant does.
+ </para>
+
+ <para>
+ If not specified, <literal>INHERIT</literal> is the default.
</para>
<para>
In <productname>PostgreSQL</productname> versions before 16,
- the <literal>GRANT</literal> statement did not support
+ the <command>GRANT</command> command did not support
<literal>WITH INHERIT</literal>. Therefore, changing this role-level
property would also change the behavior of already-existing grants.
This is no longer the case.
@@ -293,9 +293,12 @@ in sync when changing the above synopsis!
<para>
The <literal>IN ROLE</literal> 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 or to disallow <literal>SET ROLE</literal>; use a
- separate <command>GRANT</command> command to do that.)
+ roles. The new role will have the <literal>SET</literal> option
+ on the named role(s), and the <literal>INHERIT</literal> option
+ unless the <literal>NOINHERIT</literal> attribute has been specified for this role.
+ The new role will not have the <literal>ADMIN</literal> option.
+ See the <command>GRANT</command> command for modifying these options
+ after the new role is created.
</para>
</listitem>
</varlistentry>
@@ -305,8 +308,11 @@ in sync when changing the above synopsis!
<listitem>
<para>
The <literal>ROLE</literal> 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 <quote>group</quote>.
+ existing roles to be automatically added as members, with the
+ <literal>SET</literal> option, of the new role. Any named roles with
+ the <literal>INHERIT</literal> attribute will also have the <literal>INHERIT</literal>
+ option in the membership grant.
+ This in effect makes the new role a <quote>group</quote>.
</para>
</listitem>
</varlistentry>
@@ -315,10 +321,9 @@ in sync when changing the above synopsis!
<term><literal>ADMIN</literal> <replaceable class="parameter">role_name</replaceable></term>
<listitem>
<para>
- The <literal>ADMIN</literal> clause is like <literal>ROLE</literal>,
- but the named roles are added to the new role <literal>WITH ADMIN
- OPTION</literal>, giving them the right to grant membership in this role
- to others.
+ The <literal>ADMIN</literal> clause behaves identical to the <literal>ROLE</literal> clause,
+ but the named roles are also added to the new role(s) with the <literal>ADMIN</literal> option,
+ giving them the right to grant membership in this role to others.
</para>
</listitem>
</varlistentry>
@@ -361,15 +366,19 @@ in sync when changing the above synopsis!
</para>
<para>
- The <literal>INHERIT</literal> 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
- <command>CREATE ROLE</command> and <command>ALTER ROLE</command>. For example, being
- a member of a role with <literal>CREATEDB</literal> privilege does not immediately
- grant the ability to create databases, even if <literal>INHERIT</literal> is set;
- it would be necessary to become that role via
- <link linkend="sql-set-role"><command>SET ROLE</command></link> before
- creating a database.
+ The role attributes defined here are non-inheritable, i.e., being a
+ member of a role with, e.g., <literal>CREATEDB</literal> will not
+ allow the member to create new databases even if the membership grant
+ has the <literal>INHERIT</literal> option. Of course, if the membership
+ grant has the <literal>SET</literal> option the member role would be able to
+ <link linkend="sql-set-role"><command>SET ROLE</command></link> to the
+ createdb role and then create a new database.
+ </para>
+
+ <para>
+ The membership grants created by the
+ <literal>IN ROLE</literal>, <literal>ROLE</literal>, and <literal>ADMIN</literal>
+ clauses have the role executing this command as the grantee.
</para>
<para>
@@ -469,8 +478,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <repl
<para>
The behavior specified by the SQL standard is most closely approximated
by giving <literal>LOGIN</literal> roles
- the <literal>NOINHERIT</literal> attribute, while
- <literal>NOLOGIN</literal>roles are given the <literal>INHERIT</literal>
+ the <literal>NOINHERIT</literal> attribute, while giving
+ <literal>NOLOGIN</literal> roles the <literal>INHERIT</literal>
attribute.
</para>
--
2.34.1
