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 e3363f868a4604a26ad7d7c1913d42ef6c8bbcf3..207fdcc0da80ab4a1d9a407ffeb05fff870f79f8 100644 (file)
--- a/doc/src/sgml/ref/alter_default_privileges.sgml
+++ b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -100,9 +100,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.
   
 
   
@@ -114,6 +112,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
 
@@ -134,10 +142,10 @@ REVOKE [ GRANT OPTION FOR ]
      
       The name of an existing schema.  If specified, the default privileges
       are altered for objects later created in that schema.
-      If IN SCHEMA is omitted, the global default privileges
+      If IN SCHEMAliteral> is omitted, the global default privileges
       are altered.
-      IN SCHEMA> is not allowed when using ON SCHEMAS
-      as schemas can't be nested.
+      IN SCHEMAliteral> is not allowed when setting privileges
+      for schemas, since schemas can't be nested.
      
     
    
@@ -206,11 +214,19 @@ 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:
-
+   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.
+