From 6c618553cc21639e774f6fd108423134139bfc0a Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Fri, 27 Oct 2023 17:44:19 +0200
Subject: [PATCH] Improve ALTER DEFAULT PRIVILEGES documentation

Clarify that default privileges are only applied to objects
created by the target role.  This has been a frequent source
of misunderstandings.

Per request from David Burns.

Author: Laurenz Albe
Reviewed-by: Michael Banck
Discussion: https://postgr.es/m/LV2PR12MB5725F7C1B8EB2FC38829F276E7399%40LV2PR12MB5725.namprd12.prod.outlook.com
---
 doc/src/sgml/ref/alter_default_privileges.sgml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml
index f1d54f5aa3..cf0ffa9c49 100644
--- a/doc/src/sgml/ref/alter_default_privileges.sgml
+++ b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -90,7 +90,10 @@ REVOKE [ GRANT OPTION FOR ]
   <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,
+   affect privileges assigned to already-existing objects.)  <command>ALTER
+   DEFAULT PRIVILEGES</command> changes default privileges only for objects
+   that will be created by the user that executed the statement (or by
+   <replaceable>target_role</replaceable>, if specified).  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.
@@ -138,6 +141,11 @@ REVOKE [ GRANT OPTION FOR ]
      <para>
       The name of an existing role of which the current role is a member.
       If <literal>FOR ROLE</literal> is omitted, the current role is assumed.
+      Default privileges are only changed for new objects created by the
+      <replaceable>target_role</replaceable>.  There is no way to set default
+      privileges for objects created by arbitrary roles; for that, you'd have
+      to run <command>ALTER DEFAULT PRIVILEGES</command> for each role that can
+      create objects.
      </para>
     </listitem>
    </varlistentry>
-- 
2.41.0

