agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Fujii Masao <masao.fujii@oss.nttdata.com>
To: Robert Treat <rob@xzilla.net>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Add missing references to database object statistics manipulation functions in documentation
Date: Wed, 11 Jun 2025 12:50:44 +0900
Message-ID: <9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com> (raw)
In-Reply-To: <CABV9wwPZ27D5+KA9-vt6NgS73zDN0ffoDdDmnmxrXBQ4Y7iGJg@mail.gmail.com>
References: <7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com>
<CABV9wwPZ27D5+KA9-vt6NgS73zDN0ffoDdDmnmxrXBQ4Y7iGJg@mail.gmail.com>
On 2025/06/07 3:11, Robert Treat wrote:
> On Thu, May 22, 2025 at 7:17 AM Fujii Masao <masao.fujii@oss.nttdata.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.
I see your point and dropped that part of the patch.
> 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.
Yes, so I've updated the patch to only include the change to
the MAINTAIN privilege documentation. Patch attached.
Barring any objections, I plan to commit it.
> Additionally, this function accepts argument name version of type integer, which specifies
> the server version from which the statistics originated. This is anticipated to be helpful in
> porting statistics from older versions of PostgreSQL.
By the way, while reviewing the docs for pg_restore_relation_stats
and pg_restore_attribute_stats, I noticed this description.
While it's accurate, the parameter is currently always ignored.
Should we document that explicitly? Otherwise, users might waste time
trying to figure out what value to set, even though it has no effect.
Alternatively, since this isn’t a parameter most users care about,
maybe we should just remove the description altogether? Thoughts?
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
From 3be5abe72c672f0a75203375ca49f5bb1ecf2949 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Wed, 11 Jun 2025 11:34:24 +0900
Subject: [PATCH v2] doc: Document that MAINTAIN privilege allows statistics
manipulation functions.
Database object statistics manipulation functions were introduced
in PostgreSQL 18 and are permitted under the MAINTAIN privilege.
However, the documentation previously did not mention these functions
in the list of allowed operations.
This commit updates the MAINTAIN privilege documentation to
explicitly include statistics manipulation functions, clarifying
what the privilege covers.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com
---
doc/src/sgml/ddl.sgml | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
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>
--
2.49.0
Attachments:
[text/plain] v2-0001-doc-Document-that-MAINTAIN-privilege-allows-stati.patch (1.6K, ../9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com/2-v2-0001-doc-Document-that-MAINTAIN-privilege-allows-stati.patch)
download | inline diff:
From 3be5abe72c672f0a75203375ca49f5bb1ecf2949 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Wed, 11 Jun 2025 11:34:24 +0900
Subject: [PATCH v2] doc: Document that MAINTAIN privilege allows statistics
manipulation functions.
Database object statistics manipulation functions were introduced
in PostgreSQL 18 and are permitted under the MAINTAIN privilege.
However, the documentation previously did not mention these functions
in the list of allowed operations.
This commit updates the MAINTAIN privilege documentation to
explicitly include statistics manipulation functions, clarifying
what the privilege covers.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com
---
doc/src/sgml/ddl.sgml | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
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>
--
2.49.0
view thread (4+ messages) latest in thread
Message-ID: <9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com>
Permalink: ../9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com/
Also on: postgresql.org/message-id/9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: masao.fujii@oss.nttdata.com, rob@xzilla.net, pgsql-docs@lists.postgresql.org
Subject: Re: Add missing references to database object statistics manipulation functions in documentation
In-Reply-To: <9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox