Documentation Source Text

Check-in [e1960990d2]
Login

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

Overview
Comment:Enable a table-of-contents on the WAL documentation. Fix typos in the previous check-in.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: e1960990d2b570a01ff63005766aff51fb1c229e
User & Date: drh 2016-09-13 20:39:52
Context
2016-09-13
22:40
Version 3.14.2 check-in: bf7ce59b7b user: drh tags: trunk, release, version-3.14.2
20:39
Enable a table-of-contents on the WAL documentation. Fix typos in the previous check-in. check-in: e1960990d2 user: drh tags: trunk
20:28
Add a section to the WAL documentation that describes some of the scenarios in which a query can get SQLITE_BUSY. check-in: 9466a94ec8 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/wal.in.

1
2
3
4
5
6
7
8
9
10
11
...
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532

533
534
535
536
537
538
539
<title>Write-Ahead Logging</title>
<tcl>hd_keywords {WAL} {write-ahead log} {WAL mode}</tcl>

<fancy_format>

<h1>Overview</h1>

<p>The default method by which SQLite implements
[atomic commit | atomic commit and rollback] is a [rollback journal].
Beginning with [version 3.7.0], a new "Write-Ahead Log" option
(hereafter referred to as "WAL") is available.</p>
................................................................................
^As long as exactly one connection is using a shared-memory wal-index, 
the locking mode can be changed freely between NORMAL and EXCLUSIVE.  
^It is only when the shared-memory wal-index is omitted, when the locking 
mode is EXCLUSIVE prior to the first WAL-mode database access, that the 
locking mode is stuck in EXCLUSIVE.</p>

<tcl>hd_fragment busy {WAL-mode read blocking}</tcl>
<h1>Sometimes Queries Return [SQLITE_BUSY] In WAL Mode</h1>

<p>The [advantages of WAL-mode|second advantage of WAL-mode] is that
writers do not block readers and readers to do not block writers.
This is <u>mostly</u> true.
But there are some obscure cases where a query against a WAL-mode
database can return [SQLITE_BUSY], so applications should be prepared
for that happenstance.

<p>Cases where a query against a WAL-mode database returns [SQLITE_BUSY]
include the following:

<ul>
<li><p>Another database connection has the database mode open
in [locking_mode|exclusive locking mode] then all queries against the
database will return [SQLITE_BUSY].  Both Chrome and Firefox open their
database files in exclusive locking mode, so attempts to read Chrome or
Firefox databases while the applications are running will run into this
problem, for example.

<li><p>
When the last connection to a particular database is closing, that
connection will acquire an exclusive lock for a short time while it
cleans up the WAL and shared-memory files.  If another database tries
to open and query the database while the first one is still in the middle

of its cleanup process, the second connection might get an [SQLITE_BUSY]
error.

<li><p>
If the last connection to a database crashed, then the first new
connection to open the database will start a recovery process.  An
exclusive lock is held during recovery.  So if a third database connection



|







 







|








|



|









|
|
>







1
2
3
4
5
6
7
8
9
10
11
...
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
<title>Write-Ahead Logging</title>
<tcl>hd_keywords {WAL} {write-ahead log} {WAL mode}</tcl>

<table_of_contents>

<h1>Overview</h1>

<p>The default method by which SQLite implements
[atomic commit | atomic commit and rollback] is a [rollback journal].
Beginning with [version 3.7.0], a new "Write-Ahead Log" option
(hereafter referred to as "WAL") is available.</p>
................................................................................
^As long as exactly one connection is using a shared-memory wal-index, 
the locking mode can be changed freely between NORMAL and EXCLUSIVE.  
^It is only when the shared-memory wal-index is omitted, when the locking 
mode is EXCLUSIVE prior to the first WAL-mode database access, that the 
locking mode is stuck in EXCLUSIVE.</p>

<tcl>hd_fragment busy {WAL-mode read blocking}</tcl>
<h1>Sometimes Queries Return SQLITE_BUSY In WAL Mode</h1>

<p>The [advantages of WAL-mode|second advantage of WAL-mode] is that
writers do not block readers and readers to do not block writers.
This is <u>mostly</u> true.
But there are some obscure cases where a query against a WAL-mode
database can return [SQLITE_BUSY], so applications should be prepared
for that happenstance.

<p>Cases where a query against a WAL-mode database can return [SQLITE_BUSY]
include the following:

<ul>
<li><p>If another database connection has the database mode open
in [locking_mode|exclusive locking mode] then all queries against the
database will return [SQLITE_BUSY].  Both Chrome and Firefox open their
database files in exclusive locking mode, so attempts to read Chrome or
Firefox databases while the applications are running will run into this
problem, for example.

<li><p>
When the last connection to a particular database is closing, that
connection will acquire an exclusive lock for a short time while it
cleans up the WAL and shared-memory files.  If a second database tries
to open and query the database while the first connection
is still in the middle
of its cleanup process, the second connection might get an [SQLITE_BUSY]
error.

<li><p>
If the last connection to a database crashed, then the first new
connection to open the database will start a recovery process.  An
exclusive lock is held during recovery.  So if a third database connection