doc: vacuum full, fillfactor, and "extra space"

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

doc: vacuum full, fillfactor, and "extra space"

Justin Pryzby
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


v1-0001-doc-VACUUM-FULL-separate-paragraph-fillfactor.patch (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: doc: vacuum full, fillfactor, and "extra space"

Fabien COELHO-3

Hello Justin,

> 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.

Patch applies and compiles.

Given that the paragraph begins with "Plain VACUUM (without FULL)", it is
better to have the VACUUM FULL explanations on a separate paragraph, and
the fillfactor precision makes it explicit about what it does, although it
could also be material for the NOTES section below.

--
Fabien.


Reply | Threaded
Open this post in threaded view
|

Re: doc: vacuum full, fillfactor, and "extra space"

Justin Pryzby
On Fri, Dec 27, 2019 at 11:58:18AM +0100, Fabien COELHO wrote:

>> 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.
>
> Patch applies and compiles.
>
> Given that the paragraph begins with "Plain VACUUM (without FULL)", it is
> better to have the VACUUM FULL explanations on a separate paragraph, and the

The original patch does that (Fabien agreed when I asked off list)


Reply | Threaded
Open this post in threaded view
|

Re: doc: vacuum full, fillfactor, and "extra space"

Fabien COELHO-3

>> Patch applies and compiles.
>>
>> Given that the paragraph begins with "Plain VACUUM (without FULL)", it is
>> better to have the VACUUM FULL explanations on a separate paragraph, and the
>
> The original patch does that (Fabien agreed when I asked off list)

Indeed. I may have looked at it in reverse, dunno.

I switched it to ready.

--
Fabien.


Reply | Threaded
Open this post in threaded view
|

Re: doc: vacuum full, fillfactor, and "extra space"

Justin Pryzby
In reply to this post by Justin Pryzby
Rebased against 40d964ec997f64227bc0ff5e058dc4a5770a70a9

v2-0001-doc-VACUUM-FULL-separate-paragraph-fillfactor.patch (1K) Download Attachment