Doc: clarify behavior of ALTER DEFAULT PRIVILEGES ... IN SCHEMA.

The existing text stated that "Default privileges that are specified
per-schema are added to whatever the global default privileges are for
the particular object type".  However, that bare-bones observation is
not quite clear enough, as demonstrated by the complaint in bug #16124.
Flesh it out by stating explicitly that you can't revoke built-in
default privileges this way, and by providing an example to drive
the point home.

Back-patch to all supported branches, since it's been like this
from the beginning.

Discussion: https://postgr.es/m/16124-423d8ee4358421bc@postgresql.org

diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml
index 583f65fad6c6b124a696540e725d77b1d8b5f5cb..f1d54f5aa35f9ce1e50d7d13cd926d92554e4e9e 100644 (file)
--- a/doc/src/sgml/ref/alter_default_privileges.sgml
+++ b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -106,9 +106,7 @@ REVOKE [ GRANT OPTION FOR ]
    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.  Default privileges
-   that are specified per-schema are added to whatever the global default
-   privileges are for the particular object type.
+   or just for objects created in specified schemas.
   
 
   
@@ -120,6 +118,16 @@ REVOKE [ GRANT OPTION FOR ]
    ALTER DEFAULT PRIVILEGES.
   
 
+  
+   Default privileges that are specified per-schema are added to whatever
+   the global default privileges are for the particular object type.
+   This means you cannot revoke privileges per-schema if they are granted
+   globally (either by default, or according to a previous ALTER
+   DEFAULT PRIVILEGES command that did not specify a schema).
+   Per-schema REVOKE is only useful to reverse the
+   effects of a previous per-schema GRANT.
+  
+
  
   Parameters
 
@@ -142,8 +150,8 @@ REVOKE [ GRANT OPTION FOR ]
       are altered for objects later created in that schema.
       If IN SCHEMA is omitted, the global default privileges
       are altered.
-      IN SCHEMA is not allowed when using ON SCHEMAS
-      as schemas can't be nested.
+      IN SCHEMA is not allowed when setting privileges
+      for schemas, since schemas can't be nested.
      
     
    
@@ -212,10 +220,18 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser
   
    Remove the public EXECUTE permission that is normally granted on functions,
    for all functions subsequently created by role admin:
-
 
 ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
-
+
+   Note however that you cannot accomplish that effect
+   with a command limited to a single schema.  This command has no effect,
+   unless it is undoing a matching GRANT:
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
+
+   That's because per-schema default privileges can only add privileges to
+   the global setting, not remove privileges granted by it.
+