From c2122aae636d7121d5cdb64ad1444e1df7f69257 Mon Sep 17 00:00:00 2001 From: Nathan Bossart Date: Thu, 22 Jun 2023 15:48:38 -0700 Subject: [PATCH] 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 --- doc/src/sgml/ref/analyze.sgml | 8 +----- doc/src/sgml/ref/cluster.sgml | 6 +---- doc/src/sgml/ref/lock.sgml | 6 ++--- .../sgml/ref/refresh_materialized_view.sgml | 6 ++--- doc/src/sgml/ref/reindex.sgml | 26 +++++++++---------- doc/src/sgml/ref/vacuum.sgml | 8 +----- doc/src/sgml/user-manag.sgml | 3 ++- 7 files changed, 22 insertions(+), 41 deletions(-) diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 30a893230e..954491b5df 100644 --- 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 f0dd7faed5..06f3d269e6 100644 --- 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 8524182211..070855da18 100644 --- 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 pg_maintain - role. If the user has MAINTAIN, + lockmode. + If the user has MAINTAIN, UPDATE, DELETE, or TRUNCATE privileges on the table, any 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 4d79b6ae7f..19737668cd 100644 --- 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 23f8c7630b..bef3486843 100644 --- 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 445325e14c..c42bbea9e2 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -445,14 +445,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ 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 b6c37ccef2..e1540dd481 100644 --- 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