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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 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
Reply | Threaded
Open this post in threaded view
|

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

Peter Eisentraut-6
On 2020-01-20 06:30, Justin Pryzby wrote:
> Rebased against 40d964ec997f64227bc0ff5e058dc4a5770a70a9

I'm not sure that description of parallel vacuum in the middle of
non-full vs. full vacuum is actually that good.  I think those sentences
should be moved to a separate paragraph.

About your patch, I don't think this is clearer.  The fillfactor stuff
is valid to be mentioned, but the way it's being proposed makes it sound
like the main purpose of VACUUM FULL is to bloat the table to make
fillfactor room.  The "no extra space" wording made sense to me, with
the fillfactor business perhaps worth being put into a parenthetical note.

--
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


Reply | Threaded
Open this post in threaded view
|

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

akapila
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<[hidden email]> wrote:
>
> On 2020-01-20 06:30, Justin Pryzby wrote:
> > Rebased against 40d964ec997f64227bc0ff5e058dc4a5770a70a9
>
> I'm not sure that description of parallel vacuum in the middle of
> non-full vs. full vacuum is actually that good.
>

I have done like that because parallel vacuum is the default.  I mean
when the user runs vacuum command, it will invoke workers to perform
index cleanup based on some conditions.

>  I think those sentences
> should be moved to a separate paragraph.
>

It seems more natural to me to add immediately after vacuum
explanation, but I might be wrong.  After the above explanation, if
you still think it is better to move into a separate paragraph, I can
do that.


--
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com


Reply | Threaded
Open this post in threaded view
|

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

David Steele
On 1/30/20 6:54 AM, Amit Kapila wrote:

> On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
> <[hidden email]> wrote:
>>
>> On 2020-01-20 06:30, Justin Pryzby wrote:
>>> Rebased against 40d964ec997f64227bc0ff5e058dc4a5770a70a9
>>
>> I'm not sure that description of parallel vacuum in the middle of
>> non-full vs. full vacuum is actually that good.
>
> I have done like that because parallel vacuum is the default.  I mean
> when the user runs vacuum command, it will invoke workers to perform
> index cleanup based on some conditions.
>
>>   I think those sentences
>> should be moved to a separate paragraph.
>
> It seems more natural to me to add immediately after vacuum
> explanation, but I might be wrong.  After the above explanation, if
> you still think it is better to move into a separate paragraph, I can
> do that.
Peter, do you still think this should be moved into a separate paragraph?

Regards,
--
-David
[hidden email]


Reply | Threaded
Open this post in threaded view
|

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

akapila
In reply to this post by Peter Eisentraut-6
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<[hidden email]> wrote:
>
> On 2020-01-20 06:30, Justin Pryzby wrote:
>
> About your patch, I don't think this is clearer.  The fillfactor stuff
> is valid to be mentioned, but the way it's being proposed makes it sound
> like the main purpose of VACUUM FULL is to bloat the table to make
> fillfactor room.  The "no extra space" wording made sense to me, with
> the fillfactor business perhaps worth being put into a parenthetical note.
>

Justin, would you like to address this comment of Peter E.?

--
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com