From: Bruce Momjian <bruce@momjian.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Cc: Robert Haas <robertmhaas@gmail.com>
Subject: Re: CREATE ROLE inheritance details
Date: Fri, 26 Jan 2024 19:18:25 -0500
Message-ID: <ZbRL0TwcXjwJ7j-q@momjian.us> (raw)
In-Reply-To: <CAKFQuwY38v5MXfCDqvEqS_XDEaPGjZLvffNBs9Gzc_XsctMMhA@mail.gmail.com>
References: <Zab9GiV63EENDcWG@momjian.us>
<8e1b78c8ad45febf2e530e1f7508ee01c68bf2ef.camel@cybertec.at>
<ZagCmb_F0azUtDdn@momjian.us>
<CAKFQuwY38v5MXfCDqvEqS_XDEaPGjZLvffNBs9Gzc_XsctMMhA@mail.gmail.com>
On Wed, Jan 17, 2024 at 02:32:47PM -0700, David G. Johnston wrote:
> I had a go at this.
>
> I went with a more "bullet item" approach with my wording for INHERIT/
> NOINHERIT.
I tried to address that.
> 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.
Because the CREATE ROLE is the way to create roles, and GRANT does much
more than just grant membership, I ended up moving the details from the
GRANT page to the CREATE ROLE page.
> We consistently say what the default is for these attribute pairs, do so here
> as well.
I added that, I hope in all the right places.
> 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.
Yes, that needed help.
> 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.
I adjusted that working, but in a different way. Patch attached.
I also found we didn't document that GRANT can be used to modify a
membership's attributes even after it is created; I added that.
Just a reminder, this is for PG 16 and master.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
[text/x-diff] role.diff (9.6K, ../ZbRL0TwcXjwJ7j-q@momjian.us/2-role.diff)
download | inline diff:diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgmlindex 8dd2a6395c..f2dc841b85 100644--- a/doc/src/sgml/ref/create_role.sgml+++ b/doc/src/sgml/ref/create_role.sgml@@ -133,24 +133,33 @@ in sync when changing the above synopsis!
<term><literal>NOINHERIT</literal></term>
<listitem>
<para>
- When the <literal>GRANT</literal> statement is used to confer- membership in one role to another role, the <literal>GRANT</literal>- may use the <literal>WITH INHERIT</literal> clause to specify whether- the privileges of the granted role should be <quote>inherited</quote>- by the new member. If the <literal>GRANT</literal> statement does not- specify either inheritance behavior, the new <literal>GRANT</literal>- will be created <literal>WITH INHERIT TRUE</literal> if the member- role is set to <literal>INHERIT</literal> and to- <literal>WITH INHERIT FALSE</literal> if it is set to- <literal>NOINHERIT</literal>.+ 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+ <literal>IN ROLE</literal> clause, and in later commands using+ the <literal>ROLE</literal> clause. It is also used as the+ default inheritance status when adding this role as a member+ using the <literal>GRANT</literal> command. If not specified,+ <literal>INHERIT</literal> is the default.+ </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 lacking the inherit attribute. Without role+ inheritance, the only other value of membership is the use of+ <command>SET ROLE</command>, assuming the membership chain has+ <literal>SET</literal> attributes.
</para>
<para>
In <productname>PostgreSQL</productname> versions before 16,
- the <literal>GRANT</literal> statement 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.+ inheritance was a role-level attribute. It could not be specified+ during role addition with <literal>GRANT</literal>, and changing+ this role-level property would also change the inheritance behavior+ of all existing memberships. This is no longer the case.
</para>
</listitem>
</varlistentry>
@@ -285,9 +294,13 @@ 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; use a separate <command>GRANT</command> command- to do that.)+ roles. The new membership will have the <literal>SET</literal>+ option enabled and the <literal>ADMIN</literal> option disabled.+ The <literal>INHERIT</literal> option will be enabled unless the+ <literal>NOINHERIT</literal> attribute is specified. See the <xref+ linkend="sql-grant"/> command, which has additional attribute+ control during membership creation and to modify these options+ after the new role is created.
</para>
</listitem>
</varlistentry>
@@ -297,8 +310,12 @@ 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 enabled. This in effect makes the+ new role a <quote>group</quote>. Roles named in this clause+ with role-level <literal>INHERIT</literal> attributes will have+ <literal>INHERIT</literal> enabled in the new membership. New+ memberships will have the <literal>ADMIN</literal> option disabled.
</para>
</listitem>
</varlistentry>
@@ -307,10 +324,10 @@ 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 is similar to+ <literal>ROLE</literal>, but the named roles are added as members+ of the new role with <literal>ADMIN</literal> enabled, giving+ them the right to grant membership in this role to others.
</para>
</listitem>
</varlistentry>
@@ -353,15 +370,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>
@@ -459,9 +480,11 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <repl
</para>
<para>
- The behavior specified by the SQL standard is most closely approximated- by giving users the <literal>NOINHERIT</literal> attribute, while roles are- given the <literal>INHERIT</literal> attribute.+ The behavior specified by the SQL standard is most closely approximated+ creating SQL-standard users as <productname>PostgreSQL</productname>+ roles with the <literal>NOINHERIT</literal> attribute, and SQL-standard+ roles as <productname>PostgreSQL</productname> roles with the+ <literal>INHERIT</literal> attribute.
</para>
<para>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgmlindex 1ae5770fbb..fbf98b0cad 100644--- a/doc/src/sgml/ref/grant.sgml+++ b/doc/src/sgml/ref/grant.sgml@@ -249,11 +249,14 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
<para>
This variant of the <command>GRANT</command> 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 attributes. 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 attributes of+ an existing membership, simply specify the membership with updated+ attribute values.
</para>
<para>
@@ -275,15 +278,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
</para>
<para>
- The <literal>INHERIT</literal> option, if it is set to- <literal>TRUE</literal>, 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- <literal>FALSE</literal>, 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 <literal>INHERIT</literal> and to false- if the member role is set to <literal>NOINHERIT</literal>.- See <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.+ The <literal>INHERIT</literal> option controls the inheritance status+ of the new membership; see <xref linkend="sql-createrole"/> for+ details on inheritance. If it is set to <literal>TRUE</literal>,+ it causes the new member to inherit from the granted role. If+ set to <literal>FALSE</literal>, the new member does not inherit.+ If unspecified, it defaults to the inheritance status of the role+ being added.
</para>
<para>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, david.g.johnston@gmail.com, laurenz.albe@cybertec.at, robertmhaas@gmail.com
Subject: Re: CREATE ROLE inheritance details
In-Reply-To: <ZbRL0TwcXjwJ7j-q@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox