Question about role attributes docs

On Tue, 2022-01-11 at 16:40 +0900, Shinya Kato wrote:

I have a question about the documentation on ROLE.

According to [1], INHERIT and BYPASSRLS can be specified when executing
the CREATE ROLE command. However, there is no such description in Role
Attributes in [2]. Are these concepts different from Role Attributes? Or
are they just not documented? If they need to be documented, I'll create
a patch.

[1] https://www.postgresql.org/docs/devel/sql-createrole.html
[2] https://www.postgresql.org/docs/devel/role-attributes.html

I think that is indeed an omission, and adding documentation would be a
good idea. On the other hand, a lot of that information is more or less
a duplicate of the CREATE ROLE documentation. I wonder if the latter
page could be removed altogether.

Yours,
Laurenz Albe

On 2022-01-12 02:07, Laurenz Albe wrote:

On Tue, 2022-01-11 at 16:40 +0900, Shinya Kato wrote:

I have a question about the documentation on ROLE.

According to [1], INHERIT and BYPASSRLS can be specified when
executing
the CREATE ROLE command. However, there is no such description in Role
Attributes in [2]. Are these concepts different from Role Attributes?
Or
are they just not documented? If they need to be documented, I'll
create
a patch.

[1] https://www.postgresql.org/docs/devel/sql-createrole.html
[2] https://www.postgresql.org/docs/devel/role-attributes.html

I think that is indeed an omission, and adding documentation would be a
good idea.

Thanks! I created the patch, and attached it.

On the other hand, a lot of that information is more or less
a duplicate of the CREATE ROLE documentation. I wonder if the latter
page could be removed altogether.

I think there is certainly a lot of overlap. However, I think that the
SQL commands page and the database roles page should exist separately,
and should be maintained as they are because there are parts that do not
overlap (for example, IN ROLE and ADMIN).

--
Regards,

--
Shinya Kato
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

On Tue, Feb 15, 2022 at 1:32 PM Shinya Kato <Shinya11.Kato@oss.nttdata.com>
wrote:

On 2022-01-12 02:07, Laurenz Albe wrote:

On Tue, 2022-01-11 at 16:40 +0900, Shinya Kato wrote:

I have a question about the documentation on ROLE.

According to [1], INHERIT and BYPASSRLS can be specified when
executing
the CREATE ROLE command. However, there is no such description in Role
Attributes in [2]. Are these concepts different from Role Attributes?
Or
are they just not documented? If they need to be documented, I'll
create
a patch.

[1] https://www.postgresql.org/docs/devel/sql-createrole.html
[2] https://www.postgresql.org/docs/devel/role-attributes.html

I think that is indeed an omission, and adding documentation would be a
good idea.

Thanks! I created the patch, and attached it.

On the other hand, a lot of that information is more or less
a duplicate of the CREATE ROLE documentation. I wonder if the latter
page could be removed altogether.

I think there is certainly a lot of overlap. However, I think that the
SQL commands page and the database roles page should exist separately,
and should be maintained as they are because there are parts that do not
overlap (for example, IN ROLE and ADMIN).

--
Regards,

--
Shinya Kato
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

May I suggest replacing the following verbiage in your patch
+        A role is needed to permission to inherit privileges of roles it
is a member of.
+        (except for superusers, since those bypass all permission checks).
+        If not specified, <literal>INHERIT</literal> is the default, so to
create such a role, use either:

with clearer wording such as the following:

A role can explicitly be restricted at time of creation from inheriting
privileges of
roles it is a member of (except for superusers, since those bypass all
permission checks.)
Restricting privileges is done by the <literal>NOINHERIT</literal> option.
If no option is specified, <literal>INHERIT</literal> is the default. So to
create a role that inherits
privileges, use either:

Regards,

Swaha Miller
Amazon Web Services

On 2022-02-16 06:39, Swaha Miller wrote:

On Tue, Feb 15, 2022 at 1:32 PM Shinya Kato
<Shinya11.Kato@oss.nttdata.com> wrote:

On 2022-01-12 02:07, Laurenz Albe wrote:

On Tue, 2022-01-11 at 16:40 +0900, Shinya Kato wrote:

I have a question about the documentation on ROLE.

According to [1], INHERIT and BYPASSRLS can be specified when
executing
the CREATE ROLE command. However, there is no such description in

Role

Attributes in [2]. Are these concepts different from Role

Attributes?

Or
are they just not documented? If they need to be documented, I'll

create
a patch.

[1] https://www.postgresql.org/docs/devel/sql-createrole.html
[2] https://www.postgresql.org/docs/devel/role-attributes.html

I think that is indeed an omission, and adding documentation would

be a

good idea.

Thanks! I created the patch, and attached it.

On the other hand, a lot of that information is more or less
a duplicate of the CREATE ROLE documentation. I wonder if the

latter

page could be removed altogether.

I think there is certainly a lot of overlap. However, I think that
the
SQL commands page and the database roles page should exist
separately,
and should be maintained as they are because there are parts that do
not
overlap (for example, IN ROLE and ADMIN).

--
Regards,

--
Shinya Kato
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

May I suggest replacing the following verbiage in your patch
+        A role is needed to permission to inherit privileges of roles
it is a member of.
+        (except for superusers, since those bypass all permission
checks).
+        If not specified, <literal>INHERIT</literal> is the default,
so to create such a role, use either:

with clearer wording such as the following:

A role can explicitly be restricted at time of creation from
inheriting privileges of
roles it is a member of (except for superusers, since those bypass all
permission checks.)
Restricting privileges is done by the <literal>NOINHERIT</literal>
option.
If no option is specified, <literal>INHERIT</literal> is the default.
So to create a role that inherits

privileges, use either:

Regards,

Swaha Miller
Amazon Web Services

Thank you for the review, and sorry for late reply.
I fixed it.

--
Regards,

--
Shinya Kato
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

On 2022/03/17 17:56, Shinya Kato wrote:

Thank you for the review, and sorry for late reply.
I fixed it.

Thanks for updating the patch!

I found that the patch has two trailing whitespaces.

+        A role can explicitly be restricted at time of creation from inheriting privileges of
+        roles it is a member of (except for superusers, since those bypass all permission checks.)
+        Restricting privileges is done by the <literal>NOINHERIT</literal> option.
+        If no option is specified, <literal>INHERIT</literal> is the default. So to create a role that inherits
+        privileges, use either:

It sounds strange to me that restriction of inheritance is explained at the beginning. Instead, something like the following is more intuitive and easy-to-understand to users?

------------------------
A role is given permission to inherit the privileges of roles it is a member of, by default. However, to create a role without the permission, use CREATE ROLE name NOINHERIT.
------------------------

+        A role must be explicitly given permission to bypass row-level security (RLS) policy.
+        (except for superusers, since those bypass all permission checks).

Like CREATE ROLE docs does, isn't it better to add "every" just before "row-level"?

A dot just between "policy" and "(except" should be removed.

+ <term>bypass row-level security<indexterm><primary>role</primary><secondary>privilege to bypass</secondary></indexterm></term>

"bypass" should be "bypassing" or something because a noun is used for each entry title in other places?

+ To create such a role, use <literal>CREATE ROLE <replaceable>name</replaceable> BYPASSRLS</literal>.

Isn't it better to add "as a superuser" just after "BYPASSRLS</literal>" because only a superuser can create a new role having the BYPASSRLS attribute?

+ -1 (the default) means no limit. To create such a role, use <literal>CREATE ROLE <replaceable>name</replaceable> CONNECTION LIMIT<replaceable> connlimit</replaceable> LOGIN</literal>.

"To create such a role" sounds odd to me in this context. Instead, how about something like "Specify connection limit upon role creation with CREATE ROLE name CONNECTION LIMIT 'integer'."?

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

On 2022-07-23 00:35, Fujii Masao wrote:

On 2022/03/17 17:56, Shinya Kato wrote:

Thank you for the review, and sorry for late reply.
I fixed it.

Thanks for updating the patch!

Thank you for the review!

I found that the patch has two trailing whitespaces.

Sorry, I fixed them.

+        A role can explicitly be restricted at time of creation from
inheriting privileges of
+        roles it is a member of (except for superusers, since those
bypass all permission checks.)
+        Restricting privileges is done by the
<literal>NOINHERIT</literal> option.
+        If no option is specified, <literal>INHERIT</literal> is the
default. So to create a role that inherits
+        privileges, use either:

It sounds strange to me that restriction of inheritance is explained
at the beginning. Instead, something like the following is more
intuitive and easy-to-understand to users?

------------------------
A role is given permission to inherit the privileges of roles it is a
member of, by default. However, to create a role without the
permission, use CREATE ROLE name NOINHERIT.
------------------------

+        A role must be explicitly given permission to bypass
row-level security (RLS) policy.
+        (except for superusers, since those bypass all permission 
checks).

Like CREATE ROLE docs does, isn't it better to add "every" just before
"row-level"?

A dot just between "policy" and "(except" should be removed.

+ <term>bypass row-level
security<indexterm><primary>role</primary><secondary>privilege to
bypass</secondary></indexterm></term>

"bypass" should be "bypassing" or something because a noun is used for
each entry title in other places?

+ To create such a role, use <literal>CREATE ROLE
<replaceable>name</replaceable> BYPASSRLS</literal>.

Isn't it better to add "as a superuser" just after
"BYPASSRLS</literal>" because only a superuser can create a new role
having the BYPASSRLS attribute?

+ -1 (the default) means no limit. To create such a role, use
<literal>CREATE ROLE <replaceable>name</replaceable> CONNECTION
LIMIT<replaceable> connlimit</replaceable> LOGIN</literal>.

"To create such a role" sounds odd to me in this context. Instead, how
about something like "Specify connection limit upon role creation with
CREATE ROLE name CONNECTION LIMIT 'integer'."?

I agree with what you say. I fixed everything.

--
Regards,

--
Shinya Kato
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

On Mon, Jul 25, 2022 at 12:29:54PM +0900, Shinya Kato wrote:

On 2022-07-23 00:35, Fujii Masao wrote:

On 2022/03/17 17:56, Shinya Kato wrote:

Thank you for the review, and sorry for late reply.
I fixed it.

Thanks for updating the patch!

Thank you for the review!

Patch applied back to PG 10. Commitfest status updated.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson