doc: vacuum full, fillfactor, and "extra space"
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
Attachments:
v1-0001-doc-VACUUM-FULL-separate-paragraph-fillfactor.patchtext/x-diff; charset=us-asciiDownload
From 8b05c40bdfb4605bba297fbd72f25f361e51c8d4 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@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
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.
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)
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 theThe 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.
Rebased against 40d964ec997f64227bc0ff5e058dc4a5770a70a9
Attachments:
v2-0001-doc-VACUUM-FULL-separate-paragraph-fillfactor.patchtext/x-diff; charset=us-asciiDownload
From b9f10d21de62354d953e388642fcdfc6d97a4a47 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 26 Dec 2019 18:54:28 -0600
Subject: [PATCH v2] 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 | 15 ++++++++++-----
1 file changed, 10 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 404febb..ab1b8c2 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -79,11 +79,16 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
same table. It also allows us to leverage multiple CPUs in order to process
indexes. This feature is known as <firstterm>parallel vacuum</firstterm>.
To disable this feature, one can use <literal>PARALLEL</literal> option and
- specify parallel workers as zero. <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.
+ specify parallel workers as zero.
+ </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
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
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<peter.eisentraut@2ndquadrant.com> 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
On 1/30/20 6:54 AM, Amit Kapila wrote:
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<peter.eisentraut@2ndquadrant.com> 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
david@pgmasters.net
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<peter.eisentraut@2ndquadrant.com> 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
On 28 Mar 2020, at 11:23, Amit Kapila <amit.kapila16@gmail.com> wrote:
On Wed, Jan 29, 2020 at 9:10 PM Peter Eisentraut
<peter.eisentraut@2ndquadrant.com> 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.?
This patch has been Waiting on Author since April, will you have time to
address the questions during this commitfest, or should it be moved to Returned
with Feedback?
cheers ./daniel
On 5 Jul 2020, at 13:35, Daniel Gustafsson <daniel@yesql.se> wrote:
This patch has been Waiting on Author since April, will you have time to
address the questions during this commitfest, or should it be moved to Returned
with Feedback?
This has been closed as Returned with Feedback, please feel free to open a new
entry if you return to this work.
cheers ./daniel