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

On Tue, Jun 10, 2025 at 11:50 PM Fujii Masao
<masao(dot)fujii(at)oss(dot)nttdata(dot)com> wrote:
> On 2025/06/07 3:11, Robert Treat wrote:
> > 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.
> >>
<snip>
> > 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.
>

+1 from me.

>
> > 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?
>

Ah, nice catch. It could probably be removed until it does something
useful, but if we wanted to keep it, maybe something like:

This function also accepts an argument named "version", of type
"integer", that is meant to be used to identify the server version
from which the statistics were collected. Although this argument is
not yet utilized, it is intended to support migration of statistics
from earlier PostgreSQL versions in the future.

Robert Treat
https://xzilla.net