Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uPCUM-002M8t-Rq
	for pgsql-docs@arkaria.postgresql.org; Wed, 11 Jun 2025 03:50:58 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uPCUI-00Enm7-QN
	for pgsql-docs@arkaria.postgresql.org; Wed, 11 Jun 2025 03:50:55 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <masao.fujii@oss.nttdata.com>)
	id 1uPCUI-00Enlx-IA
	for pgsql-docs@lists.postgresql.org; Wed, 11 Jun 2025 03:50:55 +0000
Received: from oss.nttdata.com ([49.212.34.109])
	by magus.postgresql.org with esmtps  (TLS1.2) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <masao.fujii@oss.nttdata.com>)
	id 1uPCUG-001M0N-0v
	for pgsql-docs@lists.postgresql.org;
	Wed, 11 Jun 2025 03:50:54 +0000
Received: from [192.168.11.2] (p1696134-ipoe.ipoe.ocn.ne.jp [118.0.93.133])
	by oss.nttdata.com (Postfix) with ESMTPSA id 99F4060716;
	Wed, 11 Jun 2025 12:50:44 +0900 (JST)
X-Virus-Status: Clean
X-Virus-Scanned: clamav-milter 0.103.11 at oss.nttdata.com
Content-Type: multipart/mixed; boundary="------------7P1ktu6fkxYzfg9QCrfB0Qm8"
Message-ID: <9ab5dbad-ab21-43bf-af73-0a2c636fbfd7@oss.nttdata.com>
Date: Wed, 11 Jun 2025 12:50:44 +0900
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Add missing references to database object statistics manipulation
 functions in documentation
To: Robert Treat <rob@xzilla.net>
Cc: pgsql-docs@lists.postgresql.org
References: <7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com>
 <CABV9wwPZ27D5+KA9-vt6NgS73zDN0ffoDdDmnmxrXBQ4Y7iGJg@mail.gmail.com>
Content-Language: en-US
From: Fujii Masao <masao.fujii@oss.nttdata.com>
In-Reply-To: 
 <CABV9wwPZ27D5+KA9-vt6NgS73zDN0ffoDdDmnmxrXBQ4Y7iGJg@mail.gmail.com>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/9ab5dbad-ab21-43bf-af73-0a2c636fbfd7%40oss.nttdata.com>
Precedence: bulk

This is a multi-part message in MIME format.
--------------7P1ktu6fkxYzfg9QCrfB0Qm8
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit



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

--------------7P1ktu6fkxYzfg9QCrfB0Qm8
Content-Type: text/plain; charset=UTF-8;
 name="v2-0001-doc-Document-that-MAINTAIN-privilege-allows-stati.patch"
Content-Disposition: attachment;
 filename*0="v2-0001-doc-Document-that-MAINTAIN-privilege-allows-stati.pa";
 filename*1="tch"
Content-Transfer-Encoding: base64

RnJvbSAzYmU1YWJlNzJjNjcyZjBhNzUyMDMzNzVjYTQ5ZjViYjFlY2YyOTQ5IE1vbiBTZXAg
MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBGdWppaSBNYXNhbyA8ZnVqaWlAcG9zdGdyZXNxbC5v
cmc+CkRhdGU6IFdlZCwgMTEgSnVuIDIwMjUgMTE6MzQ6MjQgKzA5MDAKU3ViamVjdDogW1BB
VENIIHYyXSBkb2M6IERvY3VtZW50IHRoYXQgTUFJTlRBSU4gcHJpdmlsZWdlIGFsbG93cyBz
dGF0aXN0aWNzCiBtYW5pcHVsYXRpb24gZnVuY3Rpb25zLgoKRGF0YWJhc2Ugb2JqZWN0IHN0
YXRpc3RpY3MgbWFuaXB1bGF0aW9uIGZ1bmN0aW9ucyB3ZXJlIGludHJvZHVjZWQKaW4gUG9z
dGdyZVNRTCAxOCBhbmQgYXJlIHBlcm1pdHRlZCB1bmRlciB0aGUgTUFJTlRBSU4gcHJpdmls
ZWdlLgpIb3dldmVyLCB0aGUgZG9jdW1lbnRhdGlvbiBwcmV2aW91c2x5IGRpZCBub3QgbWVu
dGlvbiB0aGVzZSBmdW5jdGlvbnMKaW4gdGhlIGxpc3Qgb2YgYWxsb3dlZCBvcGVyYXRpb25z
LgoKVGhpcyBjb21taXQgdXBkYXRlcyB0aGUgTUFJTlRBSU4gcHJpdmlsZWdlIGRvY3VtZW50
YXRpb24gdG8KZXhwbGljaXRseSBpbmNsdWRlIHN0YXRpc3RpY3MgbWFuaXB1bGF0aW9uIGZ1
bmN0aW9ucywgY2xhcmlmeWluZwp3aGF0IHRoZSBwcml2aWxlZ2UgY292ZXJzLgoKQXV0aG9y
OiBGdWppaSBNYXNhbyA8bWFzYW8uZnVqaWlAZ21haWwuY29tPgpSZXZpZXdlZC1ieTogUm9i
ZXJ0IFRyZWF0IDxyb2JAeHppbGxhLm5ldD4KRGlzY3Vzc2lvbjogaHR0cHM6Ly9wb3N0Z3Iu
ZXMvbS83YzdlMWFkNS1mZGY5LTQ4NmYtYmM2My00MGFjOTliMDQ2MWRAb3NzLm50dGRhdGEu
Y29tCi0tLQogZG9jL3NyYy9zZ21sL2RkbC5zZ21sIHwgNSArKystLQogMSBmaWxlIGNoYW5n
ZWQsIDMgaW5zZXJ0aW9ucygrKSwgMiBkZWxldGlvbnMoLSkKCmRpZmYgLS1naXQgYS9kb2Mv
c3JjL3NnbWwvZGRsLnNnbWwgYi9kb2Mvc3JjL3NnbWwvZGRsLnNnbWwKaW5kZXggZmNkMWNi
ODUzNTIuLjk2OTM2YmNkM2FlIDEwMDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvZGRsLnNnbWwK
KysrIGIvZG9jL3NyYy9zZ21sL2RkbC5zZ21sCkBAIC0yMjIzLDggKzIyMjMsOSBAQCBSRVZP
S0UgQUxMIE9OIGFjY291bnRzIEZST00gUFVCTElDOwogICAgICA8cGFyYT4KICAgICAgIEFs
bG93cyA8Y29tbWFuZD5WQUNVVU08L2NvbW1hbmQ+LCA8Y29tbWFuZD5BTkFMWVpFPC9jb21t
YW5kPiwKICAgICAgIDxjb21tYW5kPkNMVVNURVI8L2NvbW1hbmQ+LCA8Y29tbWFuZD5SRUZS
RVNIIE1BVEVSSUFMSVpFRCBWSUVXPC9jb21tYW5kPiwKLSAgICAgIDxjb21tYW5kPlJFSU5E
RVg8L2NvbW1hbmQ+LCBhbmQgPGNvbW1hbmQ+TE9DSyBUQUJMRTwvY29tbWFuZD4gb24gYQot
ICAgICAgcmVsYXRpb24uCisgICAgICA8Y29tbWFuZD5SRUlOREVYPC9jb21tYW5kPiwgPGNv
bW1hbmQ+TE9DSyBUQUJMRTwvY29tbWFuZD4sCisgICAgICBhbmQgZGF0YWJhc2Ugb2JqZWN0
IHN0YXRpc3RpY3MgbWFuaXB1bGF0aW9uIGZ1bmN0aW9ucworICAgICAgKHNlZSA8eHJlZiBs
aW5rZW5kPSJmdW5jdGlvbnMtYWRtaW4tc3RhdHNtb2QiLz4pIG9uIGEgcmVsYXRpb24uCiAg
ICAgIDwvcGFyYT4KICAgICA8L2xpc3RpdGVtPgogICAgPC92YXJsaXN0ZW50cnk+Ci0tIAoy
LjQ5LjAKCg==

--------------7P1ktu6fkxYzfg9QCrfB0Qm8--