Documentation Source Text

Check-in [62d574457f]
Login

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

Overview
Comment:Improved documentation for snapshots.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 62d574457f52d76a9d12cc7427d16678dc2937dba4cdd3db7cf69266119328bf
User & Date: drh 2018-07-23 18:32:59.051
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
Unified Diff Ignore Whitespace Patch
Changes to pages/capi3ref.in.
456
457
458
459
460
461
462



463
464
465
466
467
468
469
hd_close_aux
hd_putsnl {<hr>}

# Do a table of contents for functions
#
set funclist {}
unset -nocomplain funccnts



foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="function"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]
  set s $supported($k)
  foreach kw $keywords {







>
>
>







456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
hd_close_aux
hd_putsnl {<hr>}

# Do a table of contents for functions
#
set funclist {}
unset -nocomplain funccnts
set funccnts(0) 0
set funccnts(1) 0
set funccnts(2) 0
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="function"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]
  set s $supported($k)
  foreach kw $keywords {
Changes to pages/compile.in.
1020
1021
1022
1023
1024
1025
1026












1027
1028
1029
1030
1031
1032
1033
  This option causes SQLite to include support for the
  [rtree | R*Tree index extension].
}

COMPILE_OPTION {SQLITE_ENABLE_SESSION} {
  This option enables the [session extension].
}













COMPILE_OPTION {SQLITE_ENABLE_SORTER_REFERENCES} {
  This option activates an optimization that reduces the memory required
  by the sorter at the cost of doing additional B-tree lookups after
  the sort has occurred.
  <p>
  The default sorting procedure is to gather all information that will







>
>
>
>
>
>
>
>
>
>
>
>







1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
  This option causes SQLite to include support for the
  [rtree | R*Tree index extension].
}

COMPILE_OPTION {SQLITE_ENABLE_SESSION} {
  This option enables the [session extension].
}

COMPILE_OPTION {SQLITE_ENABLE_SNAPSHOT} {
  This option enables the code to support the [sqlite3_snapshot] object
  and its related interfaces:
  <ul>
  <li> [sqlite3_snapshot_get()] (constructor)
  <li> [sqlite3_snapshot_free()] (destructor)
  <li> [sqlite3_snapshot_open()]
  <li> [sqlite3_snapshot_cmp()]
  <li> [sqlite3_snapshot_recover()]
  </ul>
}

COMPILE_OPTION {SQLITE_ENABLE_SORTER_REFERENCES} {
  This option activates an optimization that reduces the memory required
  by the sorter at the cost of doing additional B-tree lookups after
  the sort has occurred.
  <p>
  The default sorting procedure is to gather all information that will
Changes to pages/fileformat2.in.
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
journal header may be inserted.  ^All journal headers within the same
journal must contain the same database page size and sector size.</p>

<p>^If M is -1 in the initial journal header, then the number of page records
that follow is computed by computing how many page records will fit in
the available space of the remainder of the journal file.</p>

<tcl>hd_fragment walformat {WAL format}</tcl>
<h1>The Write-Ahead Log</h1>

<p>Beginning with [version 3.7.0] ([dateof:3.7.0]), 
SQLite supports a new transaction
control mechanism called "[WAL | write-ahead log]" or "[WAL]".
^When a database is in WAL mode, all connections to that database must
use the WAL.  ^A particular database will use either a rollback journal
or a WAL, but not both at the same time.
^The WAL is always located in the same directory as the database
file and has the same name as the database file but with the string
"<tt>-wal</tt>" appended.</p>

<h2>WAL File Format</h2>

<p>A WAL file consists of a header followed by zero or more "frames".
Each frame records the revised content of a single page from the
database file.  All changes to the database are recorded by writing
frames into the WAL.  Transactions commit when a frame is written that
contains a commit marker.  ^A single WAL can and usually does record 
multiple transactions.  Periodically, the content of the WAL is
transferred back into the database file in an operation called a
"checkpoint".</p>







|














|







1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
journal header may be inserted.  ^All journal headers within the same
journal must contain the same database page size and sector size.</p>

<p>^If M is -1 in the initial journal header, then the number of page records
that follow is computed by computing how many page records will fit in
the available space of the remainder of the journal file.</p>

<tcl>hd_fragment walformat {WAL format} {WAL file format}</tcl>
<h1>The Write-Ahead Log</h1>

<p>Beginning with [version 3.7.0] ([dateof:3.7.0]), 
SQLite supports a new transaction
control mechanism called "[WAL | write-ahead log]" or "[WAL]".
^When a database is in WAL mode, all connections to that database must
use the WAL.  ^A particular database will use either a rollback journal
or a WAL, but not both at the same time.
^The WAL is always located in the same directory as the database
file and has the same name as the database file but with the string
"<tt>-wal</tt>" appended.</p>

<h2>WAL File Format</h2>

<p>A [WAL file] consists of a header followed by zero or more "frames".
Each frame records the revised content of a single page from the
database file.  All changes to the database are recorded by writing
frames into the WAL.  Transactions commit when a frame is written that
contains a commit marker.  ^A single WAL can and usually does record 
multiple transactions.  Periodically, the content of the WAL is
transferred back into the database file in an operation called a
"checkpoint".</p>
Changes to pages/wal.in.
315
316
317
318
319
320
321



























322
323
324
325
326
327
328
database file(s) using the [command-line shell] or other utility, then
restart the application.</p>

<p>The WAL journal mode will be set on all
connections to the same database file if it is set on any one connection.
</p>




























<tcl>hd_fragment {readonly} {read-only WAL databases}</tcl>
<h1>Read-Only Databases</h1>

<p>Older versions of SQLite could not read a WAL-mode database that was
read-only.  In other words, write access was required in order to read a
WAL-mode database.  This constraint was relaxed beginning with
SQLite [version 3.22.0] ([dateof:3.22.0]).







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
database file(s) using the [command-line shell] or other utility, then
restart the application.</p>

<p>The WAL journal mode will be set on all
connections to the same database file if it is set on any one connection.
</p>

<tcl>hd_fragment {walfile} {WAL file}</tcl>
<h1>The WAL File</h1>

<p>While a [database connection] is open on a WAL-mode database, SQLite
maintains an extra journal file called a "Write Ahead Log" or "WAL File".
The name of this file on disk is usually the name of the database file
with an extra "<tt>-wal</tt>" suffix, though different naming rules may
apply if SQLite is compiled with [SQLITE_ENABLE_8_3_NAMES].

<p>The WAL file exists for as long as any [database connection] has the
database open.  Usually, the WAL file is deleted automatically when the
last connection to the database closes.  However, if the last process to
have the database open exits without cleanly
shutting down the database connection, or if the 
[SQLITE_FCNTL_PERSIST_WAL] [file control] is used, then the WAL file
might be retained on disk after all connections to the database have
been closed.  The WAL file is part of the persistent state of the
database and should be kept with the database if the database is copied
or moved.  If a database file is separated from its WAL file, then
transactions that were previously committed to the database might be lost,
or the database file might become corrupted.
The only safe way to remove a WAL file is
to open the database file using one of the [sqlite3_open()] interfaces
then immediately close the database using [sqlite3_close()].

<p>The [WAL file format] is precisely defined and is cross-platform.

<tcl>hd_fragment {readonly} {read-only WAL databases}</tcl>
<h1>Read-Only Databases</h1>

<p>Older versions of SQLite could not read a WAL-mode database that was
read-only.  In other words, write access was required in order to read a
WAL-mode database.  This constraint was relaxed beginning with
SQLite [version 3.22.0] ([dateof:3.22.0]).