Add documentation on the incremental vacuum feature. (CVS 3924)

FossilOrigin-Name: b3e2cdaed3638f033437b5561705cb253449c392

diff --git a/manifest b/manifest
index df210048cc4754821d7cb2bdc9172c06219a9fec..72004120bfd6f14df89fa4f15a056927c1050732 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Fix\scompilation\sand\stesting\swith\sOMIT_INCRBLOB\sdefined.\s(CVS\s3923)
-D 2007-05-04T19:03:03
+C Add\sdocumentation\son\sthe\sincremental\svacuum\sfeature.\s(CVS\s3924)
+D 2007-05-04T19:16:30
 F Makefile.in 8cab54f7c9f5af8f22fd97ddf1ecfd1e1860de62
 F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -463,7 +463,7 @@ F www/opcode.tcl 5bd68059416b223515a680d410a9f7cb6736485f
 F www/optimizer.tcl d6812a10269bd0d7c488987aac0ad5036cace9dc
 F www/optimizing.tcl f0b2538988d1bbad16cbfe63ec6e8f48c9eb04e5
 F www/optoverview.tcl 815df406a38c9f69b27d37e8f7ede004c6d9f19e
-F www/pragma.tcl efbd34cedda8235e236840e1a2bc09e1d4ac39c5
+F www/pragma.tcl 9e5a48dc564fc2c4a1d38501402e6b45c4d3870b
 F www/quickstart.tcl 8708a4ca83fbf55c66af1782992626f20c3df095
 F www/shared.gif 265bae80c5b311c5a86e47662821076ffaf5c6ea
 F www/sharedcache.tcl 3ebec81110e606af6fd65a3c4c19562cb173b29c
@@ -475,7 +475,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 4516416b4d38679ea7d259155f241e54c4c58d7d
-R 3a3e75f1d75264be225ca608ee3178bb
-U danielk1977
-Z 0f0ffb43c67c217f676998f8fff22a56
+P a0f8adc692839d0645daf0630533a87b0543f6e8
+R 2ab54f3f4a04566149d9fc08dd42a530
+U drh
+Z d993c75ec553297a4f21ca68fdcc08cc

diff --git a/manifest.uuid b/manifest.uuid
index 327ecadbdfc2a54e6ed1a2866802ba0a308e0bc7..a333d69bac837df9003c61d1b69a2debffcaac65 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-a0f8adc692839d0645daf0630533a87b0543f6e8
\ No newline at end of file
+b3e2cdaed3638f033437b5561705cb253449c392
\ No newline at end of file

diff --git a/www/pragma.tcl b/www/pragma.tcl
index e72466f6e2ecb8e666c5db243dc2c750e40673d6..13b4f4f41f31cd76db9a66aec47fcbfa3e19bef2 100644 (file)
--- a/www/pragma.tcl
+++ b/www/pragma.tcl
@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the pragma.html file.
 #
-set rcsid {$Id: pragma.tcl,v 1.22 2007/04/02 00:53:19 drh Exp $}
+set rcsid {$Id: pragma.tcl,v 1.23 2007/05/04 19:16:30 drh Exp $}
 source common.tcl
 header {Pragma statements supported by SQLite}
 
@@ -71,26 +71,50 @@ Section {Pragmas to modify library operation} modify
 puts {
 <ul>
 <a name="pragma_auto_vacuum"></a>
-<li><p><b>PRAGMA auto_vacuum;
-       <br>PRAGMA auto_vacuum = </b><i>0 | 1</i><b>;</b></p>
-    <p> Query or set the auto-vacuum flag in the database.</p>
+<li><p><b>PRAGMA auto_vacuum;<br>
+          PRAGMA auto_vacuum = </b>
+            <i>0 | none | 1 | full | 2 | incremental</i><b>;</b></p>
+    <p>Query or set the auto-vacuum flag in the database.</p>
 
-    <p>Normally, when a transaction that deletes data from a database is
+    <p>Normally, (that is to say when auto_vacuum is 0 or "none")
+    when a transaction that deletes data from a database is
     committed, the database file remains the same size. Unused database file 
-    pages are marked as such and reused later on, when data is inserted into 
-    the database. In this mode the <a href="lang_vacuum.html">VACUUM</a>
-    command is used to reclaim unused space.</p>
-
-    <p>When the auto-vacuum flag is set, the database file shrinks when a
-    transaction that deletes data is committed (The VACUUM command is not
-    useful in a database with the auto-vacuum flag set). To support this
-    functionality the database stores extra information internally, resulting
-    in slightly larger database files than would otherwise be possible.</p>
-
-    <p>It is only possible to modify the value of the auto-vacuum flag before
-    any tables have been created in the database. No error message is 
-    returned if an attempt to modify the auto-vacuum flag is made after
-    one or more tables have been created.
+    pages are added to a "freelist" are reused for subsequent inserts.  The
+    database file does not shrink.
+    In this mode the <a href="lang_vacuum.html">VACUUM</a>
+    command can be used to reclaim unused space.</p>
+
+    <p>When the auto-vacuum flag is 1 (full), the freelist pages are
+    moved to the end of the file and the file is truncated to remove
+    the freelist pages at every commit.
+    Note, however, that auto-vacuum only truncates the freelist pages
+    from the file.  Auto-vacuum does not defragment the database nor
+    repack individual database pages the way that the
+    <a href="lang_vacuum.html">VACUUM</a> command does.  In fact, because
+    it moves pages around within the file, auto-vacuum can actually
+    make fragmentation worse.</p>
+
+    <p>Auto-vacuuming is only possible if the database stores some
+    additional information that allows each database page to be
+    traced backwards to its referer.  Therefore, auto-vacuuming must
+    be turned on before any tables are created.  It is not possible
+    to enable or disable auto-vacuum after a table has been created.</p>
+
+    <p>When the value of auto-vacuum is 2 (incremental) then the additional
+    information needed to do autovacuuming is stored in the database file
+    but autovacuuming does not occur automatically at each commit as it
+    does with auto_vacuum==full.  In incremental mode, the separate
+    <a href="#pragma_incremental_vacuum">incremental_vacuum</a> pragma must
+    be invoked to cause the vacuum to occur.  The incremental vacuum mode
+    is not persistent.  It must be set anew with each new database 
+    connection.  When a database with incremental vacuum is closed and
+    reopened, it comes up in auto_vacuum==full mode until explicitly
+    changed to incremental mode using this pragma.</p>
+
+    <p>The database connection can be changed between full and incremental
+    autovacuum mode at will.  However, the connection cannot be changed
+    in and out of the "none" mode after any table has been created in the
+    database.
     </p></li>
 
 <a name="pragma_cache_size"></a>
@@ -221,6 +245,28 @@ puts {
     </p>
 </li>
 
+<a name="pragma_incremental_vacuum"></a>
+<li><p><b>PRAGMA incremental_vacuum</b><i>(N)</i><b>;</b></p>
+    <p>The incremental_vacuum pragma causes up to <i>N</i> pages to
+    be removed from the freelist.  The database file is truncated by
+    the same amount.  The incremental_vacuum pragma has no effect if
+    the database is not in
+    <a href="#pragma_auto_vacuum">auto_vacuum==incremental</a> mode
+    or if there are no pages on the freelist.  If there are fewer than
+    <i>N</i> pages on the freelist, then the entire freelist is cleared.</p>
+
+    <p>As of version 3.3.18 (the first version that supports
+    incremental_vacuum) this feature is still experimental.  Possible
+    future changes include enhancing incremental vacuum to do
+    defragmentation and node repacking just as the full-blown
+    <a href="lang_vacuum.html">VACUUM</a> command does.  And
+    incremental vacuum may be promoted from a pragma to a separate
+    SQL command, or perhaps some variation on the VACUUM command.
+    Programmers are cautioned to not become enamored with the
+    current syntax or functionality as it is likely to change.</p>
+</li>
+
+
 <a name="pragma_legacy_file_format"></a>
 <li><p><b>PRAGMA legacy_file_format;
        <br>PRAGMA legacy_file_format = <i>ON | OFF</i></b></p>