Re: Version 14/15 documentation Section "Alter Default Privileges"

On Fri, 2023-11-03 at 12:53 -0400, Bruce Momjian wrote:
> I have developed the attached patch on top of the alter default patch I
> just applied.  It is more radical, making FOR ROLE clearer, and also
> moving my new FOR ROLE text up to the first paragraph, and reordering
> the paragraphs to be clearer.
>
> I think this is too radical for backpatch to 11/12, but I think
> 16/master makes sense after the minor releases next week.

I think it is a good idea to move part of the text to a new paragraph.

> --- a/doc/src/sgml/ref/alter_default_privileges.sgml
> +++ b/doc/src/sgml/ref/alter_default_privileges.sgml
> @@ -90,23 +90,14 @@ REVOKE [ GRANT OPTION FOR ]
> [...]
> +   As a non-superuser, you can change default privileges only for yourself
> +   and for roles that you are a member of.  These privileges are not
> +   inherited, so member roles must use <command>SET ROLE</command> to
> +   access these privileges, or <command>ALTER DEFAULT PRIVILEGES</command>
> +   must be run for each member role.  Privileges can be set globally
> +   (i.e., for all objects created in the current database), or just for
> +   objects created in specified schemas.

That this paragraph is not clear enough about who gets the privileges and
who creates the objects, and that is one of the difficulties in understanding
ALTER DEFAULT PRIVILEGES.

Perhaps:

 <para>
  <command>ALTER DEFAULT PRIVILEGES</command> allows you to set the privileges
  that will be applied to objects created in the future.  (It does not
  affect privileges assigned to already-existing objects.)   Privileges can be
  set globally (i.e., for all objects created in the current database), or
  just for objects created in specified schemas.
 </para>

 <para>
  As a non-superuser, you can change default privileges only on objects created
  by yourself or by roles that you are a member of.  If you alter the default
  privileges for a role, only objects created by that role will be affected.
  It is not sufficient to be a member of that role; member roles must use
  <command>SET ROLE</command> to assume the identity of the role for which
  default privileges were altered.
 </para>

 <para>
  There is no way to change the default privileges for objects created by
  any role.  You have run <command>ALTER DEFAULT PRIVILEGES</command> for all
  roles that can create objects whose default privileges should be modified.
 </para>

> @@ -136,12 +140,9 @@ REVOKE [ GRANT OPTION FOR ]
>      <term><replaceable>target_role</replaceable></term>
>      <listitem>
>       <para>
> -      The name of an existing role of which the current role is a member.
> -      Default access privileges are not inherited, so member roles
> -      must use <command>SET ROLE</command> to access these privileges,
> -      or <command>ALTER DEFAULT PRIVILEGES</command> must be run for
> -      each member role.  If <literal>FOR ROLE</literal> is omitted,
> -      the current role is assumed.
> +      If <literal>FOR ROLE</literal> is specified, this is the role that
> +      will be assigned the new default privileges, or the current role
> +      if not specified.

This is downright wrong; the "target_role" will *not* be assigned any
privileges.

Perhaps:

 <para>
  Default privileges are changed only for objects created by
  <replaceable>target_role</replaceable>.  If <literal>FOR ROLE</literal>
  is omitted, the current role is assumed.
 </para>

Yours,
Laurenz Albe