Hi,
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?
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
From 6e02b416f7742adb6fe82aef4692d455a27d4cf6 Mon Sep 17 00:00:00 2001
From: Fujii Masao
Date: Thu, 22 May 2025 16:35:45 +0900
Subject: [PATCH v1] doc: Add documentation references for database object
statistics functions.
Database object statistics manipulation functions were introduced
in PostgreSQL 18. However, references to these functions were missing
in several relevant parts of the documentation.
For example, the documentation for the MAINTAIN privilege lists
permitted operations but omitted mention of the statistics functions,
even though they are allowed under that privilege. Similarly,
the description of the pg_class catalog explains which operations
can update fields like reltuples, but did not include the statistics
functions, which also affect these fields.
This commit updates the documentation to explicitly reference
database object statistics manipulation functions where appropriate.
---
doc/src/sgml/catalogs.sgml | 24
doc/src/sgml/ddl.sgml | 5 +++--
doc/src/sgml/perform.sgml | 10 +++---
3 files changed, 26 insertions(+), 13 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index cbd4e40a320..60d4c989aba 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2032,8 +2032,10 @@ SCRAM-SHA-256$:&l
Size of the on-disk representation of this table in pages (of size
BLCKSZ). This is only an estimate used by the
planner. It is updated by VACUUM,
- ANALYZE, and a
few DDL commands such as
- CREATE INDEX.
+ ANALYZE, a few
DDL commands such as
+ CREATE INDEX,
+ pg_restore_relation_stats, and
+ pg_clear_relation_stats.
@@ -2044,8 +2046,10 @@ SCRAM-SHA-256$:&l
Number of live rows in the table. This is only an estimate used by
the planner. It is updated by VACUUM,
- ANALYZE, and a
few DDL commands such as
- CREATE INDEX.
+ ANALYZE, a few
DDL commands such as
+ CREATE INDEX,
+ pg_restore_relation_stats, and
+ pg_clear_relation_stats.
If the table has never yet been vacuumed or
analyzed, reltuples
contains -1 indicating that the row count is
@@ -2061,8 +2065,10 @@ SCRAM-SHA-256$:&l
Number of pages that are marked all-visible in the table's
visibility map. This is only an estimate used by the
planner. It is updated by VACUUM,
- ANALYZE, and a
few DDL commands such as
- CREATE INDEX.
+ ANALYZE, a few
DDL commands such as
+ CREATE INDEX,
+ pg_restore_relation_stats, and
+ pg_clear_relation_stats.
@@ -2081,8 +2087,10 @@ SCRAM-SHA-256$:&l
It is updated by
VACUUM,
ANALYZE,
- and a few DDL commands such as
- CREATE INDEX.
+ a few DDL commands such as
+ CREATE INDEX,
+ pg_restore_relation_stats, and
+ pg_clear_relation_stats.
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;
Allows VACUUM, ANALYZE,
CLUSTER, REFRESH MATERIALIZED VIEW,
- REINDEX, and LOCK TABLE on a
- relation.
+ REINDEX, LOCK TABLE,
+ and database object statistics manipulation functions
+ (see ) on a relation.
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 106583fb296..acea2d2ac47 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1253,8 +1253,10 @@ WHERE relname LIKE 'tenk1%';
For efficiency reasons, reltuples
and relpages are not updated on-the-fly,
and so they usually contain somewhat out-of-date values.
- They are updated by VACUUM, ANALYZE,
and a
- few DDL commands such as CREATE INDEX. A
VACUUM
+ They are updated by VACUUM, ANALYZE,
+ a few DDL commands such as CREATE INDEX,
+ pg_restore_relation_stats, and
+ pg_clear_relation_stats. A VACUUM
or ANALYZE operation that does not scan the entire table
(which is commonly the case) will incrementally update the
reltuples count on
