Documentation Source Text

Check-in [0992cf9ad0]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the compile-time options document and footprint size bounds. Updates to the file format document.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 0992cf9ad0f531dc3239bf521025fcc8046898a3
User & Date: drh 2010-07-07 02:03:16
Context
2010-07-08
18:12
Update PRAGMA journal_mode documentation. Fix typos in the wal.html document. check-in: b1e171c029 user: drh tags: trunk
2010-07-07
02:03
Update the compile-time options document and footprint size bounds. Updates to the file format document. check-in: 0992cf9ad0 user: drh tags: trunk
2010-07-06
01:27
Adding first draft of WAL file format. check-in: 05824b6e6a user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/compile.in.

   575    575     that employ the BETWEEN operator.
   576    576   }
   577    577   
   578    578   COMPILE_OPTION {SQLITE_OMIT_BLOB_LITERAL} {
   579    579     When this option is defined, it is not possible to specify a blob in
   580    580     an SQL statement using the X'ABCD' syntax.
   581    581   }
          582  +
          583  +COMPILE_OPTION {SQLITE_OMIT_BTREECOUNT} {
          584  +  When this option is defined, an optimization that accelerates counting
          585  +  all entires in a table (in other words, an optimization that helps
          586  +  "SELECT count(*) FROM table" run faster) is omitted.
          587  +}
   582    588   
   583    589   COMPILE_OPTION {SQLITE_OMIT_BUILTIN_TEST} {
   584    590     A standard SQLite build includes a small amount of logic controlled
   585    591     by the [sqlite3_test_control()] interface that is used to exercise
   586    592     parts of the SQLite core that are difficult to control and measure using
   587    593     the standard API.  This option omits that built-in test logic.
   588    594   }
................................................................................
   593    599   
   594    600   COMPILE_OPTION {SQLITE_OMIT_CHECK} {
   595    601     This option causes SQLite to omit support for CHECK constraints.
   596    602     The parser will still accept CHECK constraints in SQL statements,
   597    603     they will just not be enforced.
   598    604   }
   599    605   
   600         -COMPILE_OPTION {SQLITE_OMIT_COMPLETE} {
   601         -  This option causes the [sqlite3_complete()] and [sqlite3_complete16()]
   602         -  interfaces to be omitted.
   603         -}
   604         -
   605    606   COMPILE_OPTION {SQLITE_OMIT_COMPILEOPTION_DIAGS} {
   606    607     This option is used to omit the compile-time option diagnostics available
   607    608     in SQLite, including the [sqlite3_compileoption_used()] and
   608    609     [sqlite3_compileoption_get()] C/C++ functions, the
   609    610     [sqlite_compileoption_used()] and [sqlite_compileoption_get()] SQL functions,
   610    611     and the [compile_options pragma].
   611    612   }
          613  +
          614  +COMPILE_OPTION {SQLITE_OMIT_COMPLETE} {
          615  +  This option causes the [sqlite3_complete()] and [sqlite3_complete16()]
          616  +  interfaces to be omitted.
          617  +}
   612    618   
   613    619   COMPILE_OPTION {SQLITE_OMIT_COMPOUND_SELECT} {
   614    620     This option is used to omit the compound [SELECT] functionality. 
   615    621     [SELECT] statements that use the 
   616    622     UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will 
   617    623     cause a parse error.
   618    624   }
................................................................................
   644    650     [sqlite3_global_recover()],
   645    651     [sqlite3_thread_cleanup()] and
   646    652     [sqlite3_memory_alarm()] interfaces.
   647    653   }
   648    654   
   649    655   COMPILE_OPTION {SQLITE_OMIT_DISKIO} {
   650    656     This option omits all support for writing to the disk and forces
   651         -  databases to exist in memory only.
          657  +  databases to exist in memory only.  This option has not been 
          658  +  maintained and probably does not work with newer versions of SQLite.
   652    659   }
   653    660   
   654    661   COMPILE_OPTION {SQLITE_OMIT_EXPLAIN} {
   655    662     Defining this option causes the [EXPLAIN] command to be omitted from the
   656    663     library. Attempting to execute an [EXPLAIN] statement will cause a parse
   657    664     error.
   658    665   }
................................................................................
   706    713   
   707    714   COMPILE_OPTION {SQLITE_OMIT_LOCALTIME} {
   708    715     This option omits the "localtime" modifier from the date and time
   709    716     functions.  This option is sometimes useful when trying to compile
   710    717     the date and time functions on a platform that does not support the
   711    718     concept of local time.
   712    719   }
          720  +
          721  +COMPILE_OPTION {SQLITE_OMIT_LOOKASIDE} {
          722  +  This option omits the [lookaside memory allocator].
          723  +}
   713    724   
   714    725   COMPILE_OPTION {SQLITE_OMIT_MEMORYDB} {
   715    726     When this is defined, the library does not respect the special database
   716    727     name ":memory:" (normally used to create an [in-memory database]). If 
   717    728     ":memory:" is passed to [sqlite3_open()], [sqlite3_open16()], or
   718    729     [sqlite3_open_v2()], a file with this name will be 
   719    730     opened or created.
................................................................................
   835    846     for which the schema contains VIEW objects. 
   836    847   }
   837    848   
   838    849   COMPILE_OPTION {SQLITE_OMIT_VIRTUALTABLE} {
   839    850     This option omits support for the [sqlite3_vtab | Virtual Table]
   840    851     mechanism in SQLite.
   841    852   }
          853  +
          854  +COMPILE_OPTION {SQLITE_OMIT_WAL} {
          855  +  This option omits the "[write-ahead log]" (a.k.a. "[WAL]") capability.
          856  +}
   842    857   
   843    858   COMPILE_OPTION {SQLITE_OMIT_WSD} {
   844    859     This options builds a version of the SQLite library that contains no
   845    860     Writable Static Data (WSD).  WSD is global variables and/or static
   846    861     variables.  Some platforms do not support WSD, and this option is necessary
   847    862     in order for SQLite to work those platforms.  
   848    863   

Changes to pages/features.in.

    12     12       (<a href="omitted.html">Features not supported</a>)</li>
    13     13   <li>A complete database is stored in a 
    14     14       <a href="onefile.html">single cross-platform disk file</a>.</li>
    15     15   <li>Supports terabyte-sized databases and gigabyte-sized strings
    16     16       and blobs.  (See <a href="limits.html">limits.html</a>.)
    17     17   <li>Small code footprint: 
    18     18       <a href="http://www.sqlite.org/cvstrac/wiki?p=SizeOfSqlite">
    19         -    less than 300KiB</a> fully configured or less
    20         -    than 180KiB with optional features omitted.</li>
           19  +    less than 325KiB</a> fully configured or less
           20  +    than 190KiB with optional features omitted.</li>
    21     21   <li><a href="speed.html">Faster</a> than popular client/server database
    22     22       engines for most common operations.</li>
    23     23   <li>Simple, easy to use <a href="c3ref/intro.html">API</a>.</li>
    24     24   <li>Written in ANSI-C.  <a href="tclsqlite.html">TCL bindings</a> included.
    25     25       Bindings for dozens of other languages 
    26     26       <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers">
    27     27       available separately.</a></li>

Changes to pages/fileformat2.in.

  1255   1255   magic number in the first 4 bytes of the WAL header is 0x377f0683 and
  1256   1256   the integers are little-endian the magic number is 0x377f0682.
  1257   1257   The checksum values are always stored in the frame header in a
  1258   1258   big-endian format regardless of which byte order is used to compute
  1259   1259   the checksum.</p>
  1260   1260   
  1261   1261   <p>The checksum algorithm only works for content which is a multiple of
  1262         -8 bytes in length.  In other words, if the puts are x(0) through x(N)
         1262  +8 bytes in length.  In other words, if the inputs are x(0) through x(N)
  1263   1263   then N must be odd.
  1264   1264   The checksum algorithm is as follows:
  1265   1265   
  1266   1266   <blockquote><pre> 
  1267   1267   s0 = s1 = 0
  1268   1268   for i from 0 to n-1 step 2:
  1269   1269      s0 += x(i) + s1;
................................................................................
  1304   1304   frame or are followed by a commit frame, then page P is read from
  1305   1305   the database file.</p>
  1306   1306   
  1307   1307   <p>To start a read transaction, the reader records the index of the last
  1308   1308   valid frame in the WAL.  The reader uses this recorded "mxFrame" value
  1309   1309   for all subsequent read operations.  New transactions can be appended
  1310   1310   to the WAL, but as long as the reader uses its original mxFrame value
  1311         -and ignores the newly appended content, it will see a consistent snapshot
  1312         -of the database from a single point in time.  This technique allows
  1313         -multiple concurrent readers to view different versions of the database
  1314         -content simultaneously.</p>
         1311  +and ignores subsequently appended content, the reader will see a 
         1312  +consistent snapshot of the database from a single point in time.  
         1313  +This technique allows multiple concurrent readers to view different 
         1314  +versions of the database content simultaneously.</p>
  1315   1315   
  1316   1316   <p>The reader algorithm in the previous paragraphs works correctly, but 
  1317   1317   because frames for page P can appear anywhere within the WAL, the
  1318   1318   reader has to scan the entire WAL looking for page P frames.  If the
  1319   1319   WAL is large (multiple megabytes is typical) that scan can be slow,
  1320   1320   and read performance suffers.  To overcome this problem, a separate
  1321   1321   data structure called the wal-index is maintained to expedite the
  1322   1322   search for frames of a particular page.</p>
  1323   1323   
  1324   1324   <tcl>hd_fragment walindexformat {WAL-index format}</tcl>
  1325   1325   <h3>4.5 WAL-Index Format</h3>
  1326   1326   
  1327   1327   <p>Conceptually, the wal-index is shared memory, though the current
  1328         -VFS implementations use a mmapped file for the wal-index.  Because
         1328  +VFS implementations use a mmapped file for the wal-index.  The mmapped
         1329  +file is in the same directory as the database and has the same name
         1330  +as the database with a "<tt>-shm</tt>" suffix appended.  Because
  1329   1331   the wal-index is shared memory, SQLite does not support 
  1330   1332   [PRAGMA journal_mode | journal_mode=WAL] 
  1331   1333   on a network filesystem when clients are on different machines.
  1332   1334   All users of the database must be able to share the same memory.</p>
  1333   1335   
  1334   1336   <p>The purpose of the wal-index is to answer this question quickly:</p>
  1335   1337   
  1336   1338   <blockquote><i>
  1337   1339   Given a page number P and a maximum WAL frame index M,
  1338   1340   return the largest WAL frame index for page P that does not exceed M, 
  1339   1341   or return NULL if there are no frames for page P that do not exceed M.
  1340   1342   </i></blockquote>
  1341   1343   
         1344  +<p>The <i>M</i> value in the previous paragraph is the "mxFrame" value
         1345  +defined in [WAL read algorithm | section 4.4] that is read at the start 
         1346  +of a transaction and which defines the maximum frame from the WAL that 
         1347  +the reader will use.</p>
  1342   1348   
  1343   1349   <p>The wal-index is transient.  After a crash, the wal-index is
  1344   1350   reconstructed from the original WAL file.  The VFS is required
  1345   1351   to either truncate or zero the header of the wal-index when the last
  1346   1352   connection to it closes.  Because the wal-index is transient, it can
  1347   1353   use an architecture-specific format; it does not have to be cross-platform.
  1348   1354   Hence, unlike the database and WAL file formats which store all values