database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-14 18:42:34 +03:00
Code Activity

Improve privilege documentation for maintenance commands.

Browse Source 
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
This commit is contained in:
Nathan Bossart
2023-06-22 15:48:38 -07:00
parent 4dbdb82513
commit c2122aae63
7 changed files with 22 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/sgml/ref/analyze.sgml
View File

@ -183,14 +183,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
<para> <para>
To analyze a table, one must ordinarily have the <literal>MAINTAIN</literal> To analyze a table, one must ordinarily have the <literal>MAINTAIN</literal>
privilege on the table or be the table's owner, a superuser, or a role with privilege on the table. However, database owners are allowed to
privileges of the
<link linkend="predefined-roles-table"><literal>pg_maintain</literal></link>
role. However, database owners are allowed to
analyze all tables in their databases, except shared catalogs. analyze all tables in their databases, except shared catalogs.
(The restriction for shared catalogs means that a true database-wide
<command>ANALYZE</command> can only be performed by superusers and roles
with privileges of <literal>pg_maintain</literal>.)
<command>ANALYZE</command> will skip over any tables that the calling user <command>ANALYZE</command> will skip over any tables that the calling user
does not have permission to analyze. does not have permission to analyze.
</para> </para>

6
doc/src/sgml/ref/cluster.sgml
View File

@ -134,11 +134,7 @@ CLUSTER [VERBOSE]
<para> <para>
To cluster a table, one must have the <literal>MAINTAIN</literal> privilege To cluster a table, one must have the <literal>MAINTAIN</literal> privilege
on the table or be the table's owner, a superuser, or a role with on the table.
privileges of the
<link linkend="predefined-roles-table"><literal>pg_maintain</literal></link>
role. <command>CLUSTER</command> will skip over any
tables that the calling user does not have permission to cluster.
</para> </para>
<para> <para>

6
doc/src/sgml/ref/lock.sgml
View File

@ -166,10 +166,8 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
<para> <para>
To lock a table, the user must have the right privilege for the specified To lock a table, the user must have the right privilege for the specified
<replaceable class="parameter">lockmode</replaceable>, or be the table's <replaceable class="parameter">lockmode</replaceable>.
owner, a superuser, or a role with privileges of the <link If the user has <literal>MAINTAIN</literal>,
linkend="predefined-roles-table"><literal>pg_maintain</literal></link>
role. If the user has <literal>MAINTAIN</literal>,
<literal>UPDATE</literal>, <literal>DELETE</literal>, or <literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>TRUNCATE</literal> privileges on the table, any <replaceable <literal>TRUNCATE</literal> privileges on the table, any <replaceable
class="parameter">lockmode</replaceable> is permitted. If the user has class="parameter">lockmode</replaceable> is permitted. If the user has

6
doc/src/sgml/ref/refresh_materialized_view.sgml
View File

@ -31,10 +31,8 @@ REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] <replaceable class="parameter">name</
<para> <para>
<command>REFRESH MATERIALIZED VIEW</command> completely replaces the <command>REFRESH MATERIALIZED VIEW</command> completely replaces the
contents of a materialized view. To execute this command you must be the contents of a materialized view. To execute this command you must have the
owner of the materialized view, have privileges of the <literal>MAINTAIN</literal>
<link linkend="predefined-roles-table"><literal>pg_maintain</literal></link>
role, or have the <literal>MAINTAIN</literal>
privilege on the materialized view. The old contents are discarded. If privilege on the materialized view. The old contents are discarded. If
<literal>WITH DATA</literal> is specified (or defaults) the backing query <literal>WITH DATA</literal> is specified (or defaults) the backing query
is executed to provide the new data, and the materialized view is left in a is executed to provide the new data, and the materialized view is left in a

26
doc/src/sgml/ref/reindex.sgml
View File

@ -292,21 +292,21 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { DA
</para> </para>
<para> <para>
Reindexing a single index or table requires being the owner of that Reindexing a single index or table requires
index or table, having privileges of the having the <literal>MAINTAIN</literal> privilege on the
<link linkend="predefined-roles-table"><literal>pg_maintain</literal></link> table. Note that while <command>REINDEX</command> on a partitioned index or
role, or having the <literal>MAINTAIN</literal> privilege on the table requires having the <literal>MAINTAIN</literal> privilege on the
table. Reindexing a schema or database requires being 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 owner of that schema or database or having privileges of the
<literal>pg_maintain</literal> role. Note specifically that it's thus <link linkend="predefined-roles-table"><literal>pg_maintain</literal></link>
role. Note specifically that it's thus
possible for non-superusers to rebuild indexes of tables owned by possible for non-superusers to rebuild indexes of tables owned by
other users. However, as a special exception, when other users. However, as a special exception,
<command>REINDEX DATABASE</command>, <command>REINDEX SCHEMA</command> <command>REINDEX DATABASE</command>, <command>REINDEX SCHEMA</command>,
or <command>REINDEX SYSTEM</command> is issued by a non-superuser, and <command>REINDEX SYSTEM</command> will skip indexes on shared catalogs
indexes on shared catalogs will be skipped unless the user owns the unless the user has the <literal>MAINTAIN</literal> privilege on the
catalog (which typically won't be the case), has privileges of the catalog.
<literal>pg_maintain</literal> role, or has the <literal>MAINTAIN</literal>
privilege on the catalog. Of course, superusers can always reindex anything.
</para> </para>
<para> <para>

8
doc/src/sgml/ref/vacuum.sgml
View File

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

3
doc/src/sgml/user-manag.sgml
View File

@ -692,7 +692,8 @@ DROP ROLE doomed_role;
<link linkend="sql-refreshmaterializedview"><command>REFRESH MATERIALIZED VIEW</command></link>, <link linkend="sql-refreshmaterializedview"><command>REFRESH MATERIALIZED VIEW</command></link>,
<link linkend="sql-reindex"><command>REINDEX</command></link>, <link linkend="sql-reindex"><command>REINDEX</command></link>,
and <link linkend="sql-lock"><command>LOCK TABLE</command></link> on all and <link linkend="sql-lock"><command>LOCK TABLE</command></link> on all
relations.</entry> relations, as if having <literal>MAINTAIN</literal> rights on those
objects, even without having it explicitly.</entry>
</row> </row>
<row> <row>
<entry>pg_use_reserved_connections</entry> <entry>pg_use_reserved_connections</entry>