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

tglsfdc · tglsfdc · commit 9dfb5b940721 · 2016-02-18T15:40:35.000-05:00
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 d287818. 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.
diff --git a/contrib/pgstattuple/expected/pgstattuple.out b/contrib/pgstattuple/expected/pgstattuple.out
@@ -17,10 +17,14 @@ select * from pgstattuple('test'::regclass);
          0 |           0 |         0 |             0 |                0 |              0 |                  0 |          0 |            0
 (1 row)
 
-select * from pgstatindex('test_pkey');
+select version, tree_level,
+    index_size / current_setting('block_size')::int as index_size,
+    root_block_no, internal_pages, leaf_pages, empty_pages, deleted_pages,
+    avg_leaf_density, leaf_fragmentation
+    from pgstatindex('test_pkey');
  version | tree_level | index_size | root_block_no | internal_pages | leaf_pages | empty_pages | deleted_pages | avg_leaf_density | leaf_fragmentation 
 ---------+------------+------------+---------------+----------------+------------+-------------+---------------+------------------+--------------------
-       2 |          0 |          0 |             0 |              0 |          0 |           0 |             0 |              NaN |                NaN
+       2 |          0 |          1 |             0 |              0 |          0 |           0 |             0 |              NaN |                NaN
 (1 row)
 
 select pg_relpages('test');
diff --git a/contrib/pgstattuple/pgstatindex.c b/contrib/pgstattuple/pgstatindex.c
@@ -72,7 +72,6 @@ typedef struct BTIndexStat
 	uint32		level;
 	BlockNumber root_blkno;
 
-	uint64		root_pages;
 	uint64		internal_pages;
 	uint64		leaf_pages;
 	uint64		empty_pages;
@@ -153,7 +152,6 @@ pgstatindex(PG_FUNCTION_ARGS)
 	}
 
 	/* -- init counters -- */
-	indexStat.root_pages = 0;
 	indexStat.internal_pages = 0;
 	indexStat.leaf_pages = 0;
 	indexStat.empty_pages = 0;
@@ -186,7 +184,11 @@ pgstatindex(PG_FUNCTION_ARGS)
 
 		/* Determine page type, and update totals */
 
-		if (P_ISLEAF(opaque))
+		if (P_ISDELETED(opaque))
+			indexStat.deleted_pages++;
+		else if (P_IGNORE(opaque))
+			indexStat.empty_pages++;	/* this is the "half dead" state */
+		else if (P_ISLEAF(opaque))
 		{
 			int			max_avail;
 
@@ -203,12 +205,6 @@ pgstatindex(PG_FUNCTION_ARGS)
 			if (opaque->btpo_next != P_NONE && opaque->btpo_next < blkno)
 				indexStat.fragments++;
 		}
-		else if (P_ISDELETED(opaque))
-			indexStat.deleted_pages++;
-		else if (P_IGNORE(opaque))
-			indexStat.empty_pages++;
-		else if (P_ISROOT(opaque))
-			indexStat.root_pages++;
 		else
 			indexStat.internal_pages++;
 
@@ -240,7 +236,7 @@ pgstatindex(PG_FUNCTION_ARGS)
 		snprintf(values[j++], 32, "%d", indexStat.level);
 		values[j] = palloc(32);
 		snprintf(values[j++], 32, INT64_FORMAT,
-				 (indexStat.root_pages +
+				 (1 +		/* include the metapage in index_size */
 				  indexStat.leaf_pages +
 				  indexStat.internal_pages +
 				  indexStat.deleted_pages +
diff --git a/contrib/pgstattuple/sql/pgstattuple.sql b/contrib/pgstattuple/sql/pgstattuple.sql
@@ -11,7 +11,11 @@ create table test (a int primary key, b int[]);
 select * from pgstattuple('test'::text);
 select * from pgstattuple('test'::regclass);
 
-select * from pgstatindex('test_pkey');
+select version, tree_level,
+    index_size / current_setting('block_size')::int as index_size,
+    root_block_no, internal_pages, leaf_pages, empty_pages, deleted_pages,
+    avg_leaf_density, leaf_fragmentation
+    from pgstatindex('test_pkey');
 
 select pg_relpages('test');
 select pg_relpages('test_pkey');
diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
@@ -153,13 +153,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>
@@ -193,13 +193,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>
@@ -243,6 +243,13 @@ leaf_fragmentation | 0
     </informaltable>
     </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
