Documentation Source Text

Check-in [59536a697b]
Login

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

Overview
Comment:Typos in the new walindex.html document.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 59536a697b01ff5510ddfa86cf2b420103cfe21d6529a131d4b86b64475bd403
User & Date: drh 2017-11-13 13:11:46.028
Context
2017-11-13
17:03
Continuing work on the walformat.html document. This is an incremental check-in. (check-in: 627feecddc user: drh tags: trunk)
13:11
Typos in the new walindex.html document. (check-in: 59536a697b user: drh tags: trunk)
2017-11-08
15:43
Updated VFS documentation. (check-in: 61fb0b3465 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/walformat.in. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<title>WAL-mode File Format</title>
<tcl>hd_keywords {wal-mode file format}</tcl>

<table_of_contents>

<p>This document describes low-level details on how [WAL mode] is
implemented on unix and windows.

<p>The separate [file format] description provides details on the
structure of a database file and of the write-head log file for
[WAL mode].  But details of the locking protocol and of the format
of the [WAL-index format] are deliberately omitted since those details
are left to descretion of individual [VFS] implementations.  This
document fills in the missing details for the unix and windows [VFSes].

<p>For completeness, some of the higher level formatting information
contains in the [file format] document and elsewhere is replicated here,
when it pertains to WAL mode processing.

<h1>Files On Disk</h1>











|



|








1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<title>WAL-mode File Format</title>
<tcl>hd_keywords {wal-mode file format}</tcl>

<table_of_contents>

<p>This document describes low-level details on how [WAL mode] is
implemented on unix and windows.

<p>The separate [file format] description provides details on the
structure of a database file and of the write-head log file used in
[WAL mode].  But details of the locking protocol and of the format
of the [WAL-index format] are deliberately omitted since those details
are left to descretion of individual [VFS] implementations.  This
document fills in those missing details for the unix and windows [VFSes].

<p>For completeness, some of the higher level formatting information
contains in the [file format] document and elsewhere is replicated here,
when it pertains to WAL mode processing.

<h1>Files On Disk</h1>
︙︙
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

[file format] document.  The [file format version numbers] at offsets
18 and 19 into the main database must both be 2 to indicate that the
database is in WAL mode.  The main database may have an arbitrary
name allowed by the underlying filesystem.  No special file suffixes
are required, though ".db", ".sqlite", and ".sqlite3" seem to be
popular choices.

<p>The write-ahead log or "wal" file is a roll-forward style log file
that records transactions that have been committed but not yet applied
to the main database.  Details on the format of the wal file are
describe in the [WAL format] subsection of the main [file format]
document.  The wal file is named by appending the four characters
"-wal" to the end of the name of the main database file.  Except
on 8+3 filesystems, such names are not allowed, and in that case
the file suffix is changed to ".WAL".  But as 8+3 filesystems are








|








32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

[file format] document.  The [file format version numbers] at offsets
18 and 19 into the main database must both be 2 to indicate that the
database is in WAL mode.  The main database may have an arbitrary
name allowed by the underlying filesystem.  No special file suffixes
are required, though ".db", ".sqlite", and ".sqlite3" seem to be
popular choices.

<p>The write-ahead log or "wal" file is a roll-forward journal
that records transactions that have been committed but not yet applied
to the main database.  Details on the format of the wal file are
describe in the [WAL format] subsection of the main [file format]
document.  The wal file is named by appending the four characters
"-wal" to the end of the name of the main database file.  Except
on 8+3 filesystems, such names are not allowed, and in that case
the file suffix is changed to ".WAL".  But as 8+3 filesystems are
︙︙
67
68
69
70
71
72
73
74
75
76
77
78

79
80
81
82
83
84
85
86
87
88
89
90
91
92


<p>When a WAL mode database is in active use, all three of the above
files exist.

<p>If the last client using the database shuts down cleanly by
calling [sqlite3_close()], then a [checkpoint] is run automatically
in order to transfer all information from the wal file
over into the main database, then both the shm file
and the wal file are unlinked.  Thus, when the database is not in
use by any client, it is usually the case that only the main
database file exists on disk.
However, if the last client did not call [sqlite3_close()] before it

shut down, then the final cleanup operation does not occur and the
shm and wal files may still exist on disk even when the database is
not in use.

<h2>Variations</h2>

<p>When [PRAGMA locking_mode=EXCLUSIVE] is set, that means that only a
single client is allowed to have the database open at one time.  Since
only a single client can use the database, the shm file is omitted.
The single client uses a buffer in heap memory as a substitute for the
memory-mapped shm file.

<h1>The WAL-Index File Format</h1>









|




>
|





|








67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


<p>When a WAL mode database is in active use, all three of the above
files exist.

<p>If the last client using the database shuts down cleanly by
calling [sqlite3_close()], then a [checkpoint] is run automatically
in order to transfer all information from the wal file
over into the main database, and both the shm file
and the wal file are unlinked.  Thus, when the database is not in
use by any client, it is usually the case that only the main
database file exists on disk.
However, if the last client did not call [sqlite3_close()] before it
shut down, or if the last client to disconnect was a read-only client,
then the final cleanup operation does not occur and the
shm and wal files may still exist on disk even when the database is
not in use.

<h2>Variations</h2>

<p>When [PRAGMA locking_mode=EXCLUSIVE] is set, only a
single client is allowed to have the database open at one time.  Since
only a single client can use the database, the shm file is omitted.
The single client uses a buffer in heap memory as a substitute for the
memory-mapped shm file.

<h1>The WAL-Index File Format</h1>
︙︙
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

when the wal file grows very large (more than 4079 frames).  Since the
default [sqlite3_wal_autocheckpoint|automatic checkpoint threshold] is
1000, WAL files rare reach the 4079 threshold needed to make the shm file
grow.

<h2>The WAL-Index Header</h2>

<p>The first 136 bytes of the shm file is a header.  The shm header has
three main divisions as follows:

<center>
<i>WAL-Index Header Divisions</i><br>
<table width="80%" border=1>
<tr><th>Bytes<th>Description
<tr><td valign=top>0..47</td><td>First copy of the WAL Index Information</td>








|








113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

when the wal file grows very large (more than 4079 frames).  Since the
default [sqlite3_wal_autocheckpoint|automatic checkpoint threshold] is
1000, WAL files rare reach the 4079 threshold needed to make the shm file
grow.

<h2>The WAL-Index Header</h2>

<p>The first 136 bytes of the shm file are a header.  The shm header has
three main divisions as follows:

<center>
<i>WAL-Index Header Divisions</i><br>
<table width="80%" border=1>
<tr><th>Bytes<th>Description
<tr><td valign=top>0..47</td><td>First copy of the WAL Index Information</td>
︙︙