Re: Add missing references to database object statistics manipulation functions in documentation

On Thu, May 22, 2025 at 7:17 AM Fujii Masao <masao(dot)fujii(at)oss(dot)nttdata(dot)com> wrote:
> I noticed that the documentation is missing references to the database
> object statistics manipulation functions such as pg_restore_relation_stats
> in a few relevant places. For instance, the MAINTAIN privilege section
> lists allowed operations but doesn't mention these functions, even though
> they're covered. Likewise, the pg_class catalog section describes
> what can update fields like reltuples, but omits these functions,
> which also affect those fields.
>
> So I'd like to propose adding these missing references to improve clarity.
> Patch attached. Thought?
>

I'm not enthusiastic about most this patch, mostly because I read the
phrasing "are updated by... <commands>" as "are kept up to date
periodically by..." rather than "can be manipulated in some way...",
especially when you consider that the current wording is most useful
because the updating commands have a secondary effect, but
pg_restore_relation_stats and pg_clear_relation_stats have a primary
purpose of updating stats and are only called in specific
circumstances, making the extra information feel excessively detailed.

That said, I do very much think it is worth adding this part in,
because most people seem to think about MAINTAINS as a way to run
utility commands, but I think they might very well be overlooking that
there are additional functions that folks will also get access to.

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index fcd1cb85352..96936bcd3ae 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2223,8 +2223,9 @@ REVOKE ALL ON accounts FROM PUBLIC;
<para>
Allows <command>VACUUM</command>, <command>ANALYZE</command>,
<command>CLUSTER</command>, <command>REFRESH MATERIALIZED VIEW</command>,
- <command>REINDEX</command>, and <command>LOCK TABLE</command> on a
- relation.
+ <command>REINDEX</command>, <command>LOCK TABLE</command>,
+ and database object statistics manipulation functions
+ (see <xref linkend="functions-admin-statsmod"/>) on a relation.
</para>
</listitem>
</varlistentry>

Robert Treat
https://xzilla.net