Improve privilege documentation for maintenance commands.

The documentation of the required privileges for maintenance
commands (i.e., VACUUM, ANALYZE, CLUSTER, LOCK TABLE, REFRESH
MATERIALIZED VIEW, and REINDEX) is redundant, inaccurate, and
difficult to read.  This commit fixes and simplifies this
documentation by removing references to ownership, superuser, and
the pg_maintain role.  In addition, this removes notes about
database-wide VACUUM and ANALYZE, clarifies matters for REINDEX on
partitioned indexes and tables, and strengthens the description of
the pg_maintain role.

Reviewed-by: Michael Paquier, Jeff Davis
Discussion: https://postgr.es/m/20230615041044.GA736001%40nathanxps13

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 30a893230e2f29beefbc7797f1c325d86d4858b0..954491b5df0f4545731b66cf0fe4baa3cdccd067 100644 (file)
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -183,14 +183,8 @@ ANALYZE [ VERBOSE ] [ table_and_columns
 
   
    To analyze a table, one must ordinarily have the MAINTAIN
-   privilege on the table or be the table's owner, a superuser, or a role with
-   privileges of the
-   pg_maintain
-   role.  However, database owners are allowed to
+   privilege on the table.  However, database owners are allowed to
    analyze all tables in their databases, except shared catalogs.
-   (The restriction for shared catalogs means that a true database-wide
-   ANALYZE can only be performed by superusers and roles
-   with privileges of pg_maintain.)
    ANALYZE will skip over any tables that the calling user
    does not have permission to analyze.
   

diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index f0dd7faed555e0417b9ef50731050b5bd6ec69cc..06f3d269e67bc4b7556c2abdeda6ba36ccd5215a 100644 (file)
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -134,11 +134,7 @@ CLUSTER [VERBOSE]
 
    
     To cluster a table, one must have the MAINTAIN privilege
-    on the table or be the table's owner, a superuser, or a role with
-    privileges of the
-    pg_maintain
-    role.  CLUSTER will skip over any
-    tables that the calling user does not have permission to cluster.
+    on the table.
    
 
    

diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml
index 8524182211d646c9f23f11d87e247ec193e1726c..070855da18b2a5a4385917eb852662ee0b27fb87 100644 (file)
--- a/doc/src/sgml/ref/lock.sgml
+++ b/doc/src/sgml/ref/lock.sgml
@@ -166,10 +166,8 @@ LOCK [ TABLE ] [ ONLY ] name [ * ]
 
    
     To lock a table, the user must have the right privilege for the specified
-    lockmode, or be the table's
-    owner, a superuser, or a role with privileges of the 
-    linkend="predefined-roles-table">pg_maintain
-    role. If the user has MAINTAIN,
+    lockmode.
+    If the user has MAINTAIN,
     UPDATE, DELETE, or
     TRUNCATE privileges on the table, any 
     class="parameter">lockmode is permitted. If the user has


diff --git a/doc/src/sgml/ref/refresh_materialized_view.sgml b/doc/src/sgml/ref/refresh_materialized_view.sgml

index 4d79b6ae7f73604054203026d51974c00f6c4fcb..19737668cdb2af65bfa4e45a089af50d03e940c4 100644 (file)

--- a/doc/src/sgml/ref/refresh_materialized_view.sgml
+++ b/doc/src/sgml/ref/refresh_materialized_view.sgml
@@ -31,10 +31,8 @@ REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] name
 
   
    REFRESH MATERIALIZED VIEW completely replaces the
-   contents of a materialized view.  To execute this command you must be the
-   owner of the materialized view, have privileges of the
-   pg_maintain
-   role, or have the MAINTAIN
+   contents of a materialized view.  To execute this command you must have the
+   MAINTAIN
    privilege on the materialized view.  The old contents are discarded.  If
    WITH DATA is specified (or defaults) the backing query
    is executed to provide the new data, and the materialized view is left in a


diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml

index 23f8c7630bafd343d81b5bc08f78f34ffed0932c..bef3486843cabd9a1fc5242ea05ed1a539435509 100644 (file)

--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -292,21 +292,21 @@ REINDEX [ ( option [, ...] ) ] { DA
   
 
   
-   Reindexing a single index or table requires being the owner of that
-   index or table, having privileges of the
-   pg_maintain
-   role, or having the MAINTAIN privilege on the
-   table.  Reindexing a schema or database requires being the
+   Reindexing a single index or table requires
+   having the MAINTAIN privilege on the
+   table.  Note that while REINDEX on a partitioned index or
+   table requires having the MAINTAIN privilege on the
+   partitioned table, such commands skip the privilege checks when processing
+   the individual partitions.  Reindexing a schema or database requires being the
    owner of that schema or database or having privileges of the
-   pg_maintain role.  Note specifically that it's thus
+   pg_maintain
+   role.  Note specifically that it's thus
    possible for non-superusers to rebuild indexes of tables owned by
-   other users.  However, as a special exception, when
-   REINDEX DATABASE, REINDEX SCHEMA
-   or REINDEX SYSTEM is issued by a non-superuser,
-   indexes on shared catalogs will be skipped unless the user owns the
-   catalog (which typically won't be the case), has privileges of the
-   pg_maintain role, or has the MAINTAIN
-   privilege on the catalog.  Of course, superusers can always reindex anything.
+   other users.  However, as a special exception,
+   REINDEX DATABASE, REINDEX SCHEMA,
+   and REINDEX SYSTEM will skip indexes on shared catalogs
+   unless the user has the MAINTAIN privilege on the
+   catalog.
   
 
   


diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml

index 445325e14c3bc1515e464f08d46ce3a3382dc33d..c42bbea9e228e0d00c0ea7dc8a0f8ad063635312 100644 (file)

--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -445,14 +445,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ 
 
    
     To vacuum a table, one must ordinarily have the MAINTAIN
-    privilege on the table or be the table's owner, a superuser, or a role with
-    privileges of the
-    pg_maintain
-    role.  However, database owners are allowed to
+    privilege on the table.  However, database owners are allowed to
     vacuum all tables in their databases, except shared catalogs.
-    (The restriction for shared catalogs means that a true database-wide
-    VACUUM can only be performed by superusers and roles
-    with privileges of pg_maintain.)
     VACUUM will skip over any tables that the calling user
     does not have permission to vacuum.
    


diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml

index b6c37ccef260fdf9512cec96f0a39e90d913b32e..e1540dd481b0c09dc892322369f321dcdbef0226 100644 (file)

--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -692,7 +692,8 @@ DROP ROLE doomed_role;
        REFRESH MATERIALIZED VIEW,
        REINDEX,
        and LOCK TABLE on all
-       relations.
+       relations, as if having MAINTAIN rights on those
+       objects, even without having it explicitly.
       
       
        pg_use_reserved_connections

diff --git a/doc/src/sgml/ref/refresh_materialized_view.sgml b/doc/src/sgml/ref/refresh_materialized_view.sgml
index 4d79b6ae7f73604054203026d51974c00f6c4fcb..19737668cdb2af65bfa4e45a089af50d03e940c4 100644 (file)
--- a/doc/src/sgml/ref/refresh_materialized_view.sgml
+++ b/doc/src/sgml/ref/refresh_materialized_view.sgml
@@ -31,10 +31,8 @@ REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] name
 
   
    REFRESH MATERIALIZED VIEW completely replaces the
-   contents of a materialized view.  To execute this command you must be the
-   owner of the materialized view, have privileges of the
-   pg_maintain
-   role, or have the MAINTAIN
+   contents of a materialized view.  To execute this command you must have the
+   MAINTAIN
    privilege on the materialized view.  The old contents are discarded.  If
    WITH DATA is specified (or defaults) the backing query
    is executed to provide the new data, and the materialized view is left in a

diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 23f8c7630bafd343d81b5bc08f78f34ffed0932c..bef3486843cabd9a1fc5242ea05ed1a539435509 100644 (file)
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -292,21 +292,21 @@ REINDEX [ ( option [, ...] ) ] { DA
   
 
   
-   Reindexing a single index or table requires being the owner of that
-   index or table, having privileges of the
-   pg_maintain
-   role, or having the MAINTAIN privilege on the
-   table.  Reindexing a schema or database requires being the
+   Reindexing a single index or table requires
+   having the MAINTAIN privilege on the
+   table.  Note that while REINDEX on a partitioned index or
+   table requires having the MAINTAIN privilege on the
+   partitioned table, such commands skip the privilege checks when processing
+   the individual partitions.  Reindexing a schema or database requires being the
    owner of that schema or database or having privileges of the
-   pg_maintain role.  Note specifically that it's thus
+   pg_maintain
+   role.  Note specifically that it's thus
    possible for non-superusers to rebuild indexes of tables owned by
-   other users.  However, as a special exception, when
-   REINDEX DATABASE, REINDEX SCHEMA
-   or REINDEX SYSTEM is issued by a non-superuser,
-   indexes on shared catalogs will be skipped unless the user owns the
-   catalog (which typically won't be the case), has privileges of the
-   pg_maintain role, or has the MAINTAIN
-   privilege on the catalog.  Of course, superusers can always reindex anything.
+   other users.  However, as a special exception,
+   REINDEX DATABASE, REINDEX SCHEMA,
+   and REINDEX SYSTEM will skip indexes on shared catalogs
+   unless the user has the MAINTAIN privilege on the
+   catalog.
   
 
   

diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 445325e14c3bc1515e464f08d46ce3a3382dc33d..c42bbea9e228e0d00c0ea7dc8a0f8ad063635312 100644 (file)
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -445,14 +445,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ 
 
    
     To vacuum a table, one must ordinarily have the MAINTAIN
-    privilege on the table or be the table's owner, a superuser, or a role with
-    privileges of the
-    pg_maintain
-    role.  However, database owners are allowed to
+    privilege on the table.  However, database owners are allowed to
     vacuum all tables in their databases, except shared catalogs.
-    (The restriction for shared catalogs means that a true database-wide
-    VACUUM can only be performed by superusers and roles
-    with privileges of pg_maintain.)
     VACUUM will skip over any tables that the calling user
     does not have permission to vacuum.
    

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index b6c37ccef260fdf9512cec96f0a39e90d913b32e..e1540dd481b0c09dc892322369f321dcdbef0226 100644 (file)
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -692,7 +692,8 @@ DROP ROLE doomed_role;
        REFRESH MATERIALIZED VIEW,
        REINDEX,
        and LOCK TABLE on all
-       relations.
+       relations, as if having MAINTAIN rights on those
+       objects, even without having it explicitly.
       
       
        pg_use_reserved_connections