Documentation Source Text

Check-in [62d574457f]
Login

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

Overview
Comment:Improved documentation for snapshots.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:62d574457f52d76a9d12cc7427d16678dc2937dba4cdd3db7cf69266119328bf
User & Date: drh 2018-07-23 18:32:59
Context
2018-07-27
23:55
Change log updates. check-in: 6a6488d91d user: drh tags: trunk
2018-07-23
18:32
Improved documentation for snapshots. check-in: 62d574457f user: drh tags: trunk
12:58
Update the size and speed spreadsheet check-in: 328bad0eed user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

   456    456   hd_close_aux
   457    457   hd_putsnl {<hr>}
   458    458   
   459    459   # Do a table of contents for functions
   460    460   #
   461    461   set funclist {}
   462    462   unset -nocomplain funccnts
          463  +set funccnts(0) 0
          464  +set funccnts(1) 0
          465  +set funccnts(2) 0
   463    466   foreach c $content {
   464    467     foreach {key title type keywords body code} $c break
   465    468     if {$type!="function"} continue
   466    469     set keywords [lsort $keywords]
   467    470     set k [preferred_keyword $keywords]
   468    471     set s $supported($k)
   469    472     foreach kw $keywords {

Changes to pages/compile.in.

  1020   1020     This option causes SQLite to include support for the
  1021   1021     [rtree | R*Tree index extension].
  1022   1022   }
  1023   1023   
  1024   1024   COMPILE_OPTION {SQLITE_ENABLE_SESSION} {
  1025   1025     This option enables the [session extension].
  1026   1026   }
         1027  +
         1028  +COMPILE_OPTION {SQLITE_ENABLE_SNAPSHOT} {
         1029  +  This option enables the code to support the [sqlite3_snapshot] object
         1030  +  and its related interfaces:
         1031  +  <ul>
         1032  +  <li> [sqlite3_snapshot_get()] (constructor)
         1033  +  <li> [sqlite3_snapshot_free()] (destructor)
         1034  +  <li> [sqlite3_snapshot_open()]
         1035  +  <li> [sqlite3_snapshot_cmp()]
         1036  +  <li> [sqlite3_snapshot_recover()]
         1037  +  </ul>
         1038  +}
  1027   1039   
  1028   1040   COMPILE_OPTION {SQLITE_ENABLE_SORTER_REFERENCES} {
  1029   1041     This option activates an optimization that reduces the memory required
  1030   1042     by the sorter at the cost of doing additional B-tree lookups after
  1031   1043     the sort has occurred.
  1032   1044     <p>
  1033   1045     The default sorting procedure is to gather all information that will

Changes to pages/fileformat2.in.

  1673   1673   journal header may be inserted.  ^All journal headers within the same
  1674   1674   journal must contain the same database page size and sector size.</p>
  1675   1675   
  1676   1676   <p>^If M is -1 in the initial journal header, then the number of page records
  1677   1677   that follow is computed by computing how many page records will fit in
  1678   1678   the available space of the remainder of the journal file.</p>
  1679   1679   
  1680         -<tcl>hd_fragment walformat {WAL format}</tcl>
         1680  +<tcl>hd_fragment walformat {WAL format} {WAL file format}</tcl>
  1681   1681   <h1>The Write-Ahead Log</h1>
  1682   1682   
  1683   1683   <p>Beginning with [version 3.7.0] ([dateof:3.7.0]), 
  1684   1684   SQLite supports a new transaction
  1685   1685   control mechanism called "[WAL | write-ahead log]" or "[WAL]".
  1686   1686   ^When a database is in WAL mode, all connections to that database must
  1687   1687   use the WAL.  ^A particular database will use either a rollback journal
................................................................................
  1688   1688   or a WAL, but not both at the same time.
  1689   1689   ^The WAL is always located in the same directory as the database
  1690   1690   file and has the same name as the database file but with the string
  1691   1691   "<tt>-wal</tt>" appended.</p>
  1692   1692   
  1693   1693   <h2>WAL File Format</h2>
  1694   1694   
  1695         -<p>A WAL file consists of a header followed by zero or more "frames".
         1695  +<p>A [WAL file] consists of a header followed by zero or more "frames".
  1696   1696   Each frame records the revised content of a single page from the
  1697   1697   database file.  All changes to the database are recorded by writing
  1698   1698   frames into the WAL.  Transactions commit when a frame is written that
  1699   1699   contains a commit marker.  ^A single WAL can and usually does record 
  1700   1700   multiple transactions.  Periodically, the content of the WAL is
  1701   1701   transferred back into the database file in an operation called a
  1702   1702   "checkpoint".</p>

Changes to pages/wal.in.

   315    315   database file(s) using the [command-line shell] or other utility, then
   316    316   restart the application.</p>
   317    317   
   318    318   <p>The WAL journal mode will be set on all
   319    319   connections to the same database file if it is set on any one connection.
   320    320   </p>
   321    321   
          322  +<tcl>hd_fragment {walfile} {WAL file}</tcl>
          323  +<h1>The WAL File</h1>
          324  +
          325  +<p>While a [database connection] is open on a WAL-mode database, SQLite
          326  +maintains an extra journal file called a "Write Ahead Log" or "WAL File".
          327  +The name of this file on disk is usually the name of the database file
          328  +with an extra "<tt>-wal</tt>" suffix, though different naming rules may
          329  +apply if SQLite is compiled with [SQLITE_ENABLE_8_3_NAMES].
          330  +
          331  +<p>The WAL file exists for as long as any [database connection] has the
          332  +database open.  Usually, the WAL file is deleted automatically when the
          333  +last connection to the database closes.  However, if the last process to
          334  +have the database open exits without cleanly
          335  +shutting down the database connection, or if the 
          336  +[SQLITE_FCNTL_PERSIST_WAL] [file control] is used, then the WAL file
          337  +might be retained on disk after all connections to the database have
          338  +been closed.  The WAL file is part of the persistent state of the
          339  +database and should be kept with the database if the database is copied
          340  +or moved.  If a database file is separated from its WAL file, then
          341  +transactions that were previously committed to the database might be lost,
          342  +or the database file might become corrupted.
          343  +The only safe way to remove a WAL file is
          344  +to open the database file using one of the [sqlite3_open()] interfaces
          345  +then immediately close the database using [sqlite3_close()].
          346  +
          347  +<p>The [WAL file format] is precisely defined and is cross-platform.
          348  +
   322    349   <tcl>hd_fragment {readonly} {read-only WAL databases}</tcl>
   323    350   <h1>Read-Only Databases</h1>
   324    351   
   325    352   <p>Older versions of SQLite could not read a WAL-mode database that was
   326    353   read-only.  In other words, write access was required in order to read a
   327    354   WAL-mode database.  This constraint was relaxed beginning with
   328    355   SQLite [version 3.22.0] ([dateof:3.22.0]).