v2-0002-Document-that-functions-that-use-the-FSM-for-will.patch

From e6e253064324dabedbc06f145c4edce9be5d54b4 Mon Sep 17 00:00:00 2001
From: John Naylor <jcnaylor@gmail.com>
Date: Mon, 11 Feb 2019 18:09:00 +0100
Subject: [PATCH v2 2/2] Document that functions that use the FSM for will
 report no free space for tables without a FSM.

---
 contrib/pgstattuple/pgstatapprox.c | 2 ++
 doc/src/sgml/pgfreespacemap.sgml   | 2 ++
 doc/src/sgml/pgstattuple.sgml      | 4 +++-
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/contrib/pgstattuple/pgstatapprox.c b/contrib/pgstattuple/pgstatapprox.c
index ff7c255a2d..23ccaaaca6 100644
--- a/contrib/pgstattuple/pgstatapprox.c
+++ b/contrib/pgstattuple/pgstatapprox.c
@@ -89,6 +89,8 @@ statapprox_heap(Relation rel, output_type *stat)
 		/*
 		 * If the page has only visible tuples, then we can find out the free
 		 * space from the FSM and move on.
+		 * Note: If a relation has no FSM, GetRecordedFreeSpace() will report
+		 * zero free space.  This is fine for the purposes of approximation.
 		 */
 		if (VM_ALL_VISIBLE(rel, blkno, &vmbuffer))
 		{
diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 0122d278e3..be6fcc4986 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -61,6 +61,8 @@
    The values stored in the free space map are not exact. They're rounded
    to precision of 1/256th of <symbol>BLCKSZ</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), and
    they're not kept fully up-to-date as tuples are inserted and updated.
+   In addition, small tables don't have a free space map, so this function
+   will return zero even if free space is available.
   </para>
 
   <para>
diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
index b17b3c59e0..8c5f53674d 100644
--- a/doc/src/sgml/pgstattuple.sgml
+++ b/doc/src/sgml/pgstattuple.sgml
@@ -527,7 +527,9 @@ approx_free_percent  | 2.09
       bit set, then it is assumed to contain no dead tuples). For such
       pages, it derives the free space value from the free space map, and
       assumes that the rest of the space on the page is taken up by live
-      tuples.
+      tuples. Small tables don't have a free space map, so in that case
+      this function will report zero free space, likewise inflating the
+      estimated number of live tuples.
      </para>
 
      <para>
-- 
2.17.1