doc: restructure ALTER DEFAULT PRIVILEGES

bmomjian · bmomjian · commit 151a0ee76dc7 · 2023-11-13T14:27:38.000-05:00
Clarify that default privileges are not inherited and reorder
paragraphs.  This is a follow up to a recent ALTER DEFAULT PRIVILEGES
doc patch.

Reported-by: Sanjay Minni

Diagnosed-by: AMpxBo=M35hcH1g4Vg=KRJ0-77FOJcvdrdiVF5KSOAdOG-LvKQ@mail.gmail.com

Co-authored-by: Laurenz Albe

Backpatch-through: 16
diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -88,25 +88,19 @@ REVOKE [ GRANT OPTION FOR ]
   <title>Description</title>
 
   <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.)  Currently,
-   only the privileges for schemas, tables (including views and foreign
-   tables), sequences, functions, and types (including domains) can be
-   altered.  For this command, functions include aggregates and procedures.
-   The words <literal>FUNCTIONS</literal> and <literal>ROUTINES</literal> are
-   equivalent in this command.  (<literal>ROUTINES</literal> is preferred
-   going forward as the standard term for functions and procedures taken
-   together.  In earlier PostgreSQL releases, only the
-   word <literal>FUNCTIONS</literal> was allowed.  It is not possible to set
-   default privileges for functions and procedures separately.)
+   <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>
-   You can change default privileges only for objects that will be created by
-   yourself or by roles that you are a member of.  The privileges can be set
-   globally (i.e., for all objects created in the current database),
-   or just for objects created in specified schemas.
+   While you can change your own default privileges and the defaults of
+   roles that you are a member of, at object creation time, new object
+   permissions are only affected by the default privileges of the current
+   role, and are not inherited from any roles in which the current role
+   is a member.
   </para>
 
   <para>
@@ -118,6 +112,19 @@ REVOKE [ GRANT OPTION FOR ]
    <command>ALTER DEFAULT PRIVILEGES</command>.
   </para>
 
+  <para>
+   Currently,
+   only the privileges for schemas, tables (including views and foreign
+   tables), sequences, functions, and types (including domains) can be
+   altered.  For this command, functions include aggregates and procedures.
+   The words <literal>FUNCTIONS</literal> and <literal>ROUTINES</literal> are
+   equivalent in this command.  (<literal>ROUTINES</literal> is preferred
+   going forward as the standard term for functions and procedures taken
+   together.  In earlier PostgreSQL releases, only the
+   word <literal>FUNCTIONS</literal> was allowed.  It is not possible to set
+   default privileges for functions and procedures separately.)
+  </para>
+
   <para>
    Default privileges that are specified per-schema are added to whatever
    the global default privileges are for the particular object type.
@@ -136,12 +143,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.
+      Change default privileges for objects created by the
+      <replaceable>target_role</replaceable>, or the current
+      role if unspecified.
      </para>
     </listitem>
    </varlistentry>
