Fix multiple bugs in contrib/pgstattuple's pgstatindex() function.

Dead or half-dead index leaf pages were incorrectly reported as live, as a
consequence of a code rearrangement I made (during a moment of severe brain
fade, evidently) in commit d287818eb514d431.

The index metapage was not counted in index_size, causing that result to
not agree with the actual index size on-disk.

Index root pages were not counted in internal_pages, which is inconsistent
compared to the case of a root that's also a leaf (one-page index), where
the root would be counted in leaf_pages.  Aside from that inconsistency,
this could lead to additional transient discrepancies between the reported
page counts and index_size, since it's possible for pgstatindex's scan to
see zero or multiple pages marked as BTP_ROOT, if the root moves due to
a split during the scan.  With these fixes, index_size will always be
exactly one page more than the sum of the displayed page counts.

Also, the index_size result was incorrectly documented as being measured in
pages; it's always been measured in bytes.  (While fixing that, I couldn't
resist doing some small additional wordsmithing on the pgstattuple docs.)

Including the metapage causes the reported index_size to not be zero for
an empty index.  To preserve the desired property that the pgstattuple
regression test results are platform-independent (ie, BLCKSZ configuration
independent), scale the index_size result in the regression tests.

The documentation issue was reported by Otsuka Kenji, and the inconsistent
root page counting by Peter Geoghegan; the other problems noted by me.
Back-patch to all supported branches, because this has been broken for
a long time.

1 files changed, 17 insertions, 10 deletions

diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
index 9cabd71166e..153330edee1 100644
--- a/doc/src/sgml/pgstattuple.sgml
+++ b/doc/src/sgml/pgstattuple.sgml
@@ -130,9 +130,9 @@ free_percent       | 1.95
     <listitem>
      <para>
       This is the same as <function>pgstattuple(regclass)</function>, except
-      that the target relation is specified by TEXT. This function is kept
+      that the target relation is specified as TEXT. This function is kept
       because of backward-compatibility so far, and will be deprecated in
-      the future release.
+      some future release.
      </para>
     </listitem>
    </varlistentry>
@@ -154,13 +154,13 @@ test=> SELECT * FROM pgstatindex('pg_cast_oid_index');
 -[ RECORD 1 ]------+------
 version            | 2
 tree_level         | 0
-index_size         | 8192
+index_size         | 16384
 root_block_no      | 1
 internal_pages     | 0
 leaf_pages         | 1
 empty_pages        | 0
 deleted_pages      | 0
-avg_leaf_density   | 50.27
+avg_leaf_density   | 54.27
 leaf_fragmentation | 0
 </programlisting>
      </para>
@@ -194,13 +194,13 @@ leaf_fragmentation | 0
        <row>
         <entry><structfield>index_size</structfield></entry>
         <entry><type>bigint</type></entry>
-        <entry>Total number of pages in index</entry>
+        <entry>Total index size in bytes</entry>
        </row>
 
        <row>
         <entry><structfield>root_block_no</structfield></entry>
         <entry><type>bigint</type></entry>
-        <entry>Location of root block</entry>
+        <entry>Location of root page (zero if none)</entry>
        </row>
 
        <row>
@@ -245,6 +245,13 @@ leaf_fragmentation | 0
     </para>
 
     <para>
+     The reported <literal>index_size</> will normally correspond to one more
+     page than is accounted for by <literal>internal_pages + leaf_pages +
+     empty_pages + deleted_pages</literal>, because it also includes the
+     index's metapage.
+    </para>
+
+    <para>
      As with <function>pgstattuple</>, the results are accumulated
      page-by-page, and should not be expected to represent an
      instantaneous snapshot of the whole index.
@@ -260,9 +267,9 @@ leaf_fragmentation | 0
     <listitem>
      <para>
       This is the same as <function>pgstatindex(regclass)</function>, except
-      that the target index is specified by TEXT. This function is kept
+      that the target index is specified as TEXT. This function is kept
       because of backward-compatibility so far, and will be deprecated in
-      the future release.
+      some future release.
      </para>
     </listitem>
    </varlistentry>
@@ -351,9 +358,9 @@ pending_tuples | 0
     <listitem>
      <para>
       This is the same as <function>pg_relpages(regclass)</function>, except
-      that the target relation is specified by TEXT. This function is kept
+      that the target relation is specified as TEXT. This function is kept
       because of backward-compatibility so far, and will be deprecated in
-      the future release.
+      some future release.
      </para>
     </listitem>
    </varlistentry>