I started writing this patch to avoid the possibly-misleading phrase: "with no
extra space" (since it's expected to typically take ~2x space, or 1x "extra"
space).
But the original phrase "with no extra space" seems to be wrong anyway, since
it actually follows fillfactor, so say that. Possibly should be backpatched.
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index ec2503d..9757352 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -75,10 +75,16 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [
<replaceable class="paramet
with normal reading and writing of the table, as an exclusive lock
is not obtained. However, extra space is not returned to the operating
system (in most cases); it's just kept available for re-use within the
- same table. <command>VACUUM FULL</command> rewrites the entire contents
- of the table into a new disk file with no extra space, allowing unused
- space to be returned to the operating system. This form is much slower and
- requires an exclusive lock on each table while it is being processed.
+ same table.
+ </para>
+
+ <para>
+ <command>VACUUM FULL</command> rewrites the entire contents of the table
+ into a new file on disk with internal space left available as determined by
+ <literal>fillfactor</literal>. If the table includes many dead tuples from
+ updates/deletes, this allows unused space to be returned to the operating
+ system. This form is much slower and requires an exclusive lock on each
+ table while it is being processed.
</para>
<para>
--
2.7.4
>From 8b05c40bdfb4605bba297fbd72f25f361e51c8d4 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryz...@telsasoft.com>
Date: Thu, 26 Dec 2019 18:54:28 -0600
Subject: [PATCH v1] doc: VACUUM FULL: separate paragraph; fillfactor
FILLFACTOR seems to apply here. Also, "no extra space" was confusing since it
could be read to mean "requires zero extra space", when actually it will always
require extra space, usually approximately the size of the table.
---
doc/src/sgml/ref/vacuum.sgml | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index ec2503d..9757352 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -75,10 +75,16 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
with normal reading and writing of the table, as an exclusive lock
is not obtained. However, extra space is not returned to the operating
system (in most cases); it's just kept available for re-use within the
- same table. <command>VACUUM FULL</command> rewrites the entire contents
- of the table into a new disk file with no extra space, allowing unused
- space to be returned to the operating system. This form is much slower and
- requires an exclusive lock on each table while it is being processed.
+ same table.
+ </para>
+
+ <para>
+ <command>VACUUM FULL</command> rewrites the entire contents of the table
+ into a new file on disk with internal space left available as determined by
+ <literal>fillfactor</literal>. If the table includes many dead tuples from
+ updates/deletes, this allows unused space to be returned to the operating
+ system. This form is much slower and requires an exclusive lock on each
+ table while it is being processed.
</para>
<para>
--
2.7.4
