Documentation Source Text

Check-in [3f48e98ec7]
Login

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

Overview
Comment:Avoid creating a master journal unless two or more databases in the transaction can actually benefit from the master journal.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 3f48e98ec765b6141d50e143a07ef24f8974171c
User & Date: drh 2016-02-22 14:58:43.885
Context
2016-02-23
00:26
New entries in the change log. (check-in: 38697e2bb0 user: drh tags: trunk)
2016-02-22
14:58
Avoid creating a master journal unless two or more databases in the transaction can actually benefit from the master journal. (check-in: 3f48e98ec7 user: drh tags: trunk)
2016-02-17
16:14
Fix the PRAGMA synchorous documentation. The default is always FULL even in WAL mode. (check-in: 3540d671bc user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/atomiccommit.in.
685
686
687
688
689
690
691






692
693
694
695
696
697
698

<p>After the master journal is constructed, its content is flushed
to disk before any further actions are taken.  On Unix, the directory
that contains the master journal is also synced in order to make sure
the master journal file will appear in the directory following a
power failure.</p>







<br clear="both">
<tcl>hd_fragment multijrnlupdate</tcl>
<h3>5.3 Updating Rollback Journal Headers</h3>
<img src="images/ac/multi-2.gif" align="right" hspace="15">

<p>The next step is to record the full pathname of the master journal file
in the header of every rollback journal.  Space to hold the master







>
>
>
>
>
>







685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704

<p>After the master journal is constructed, its content is flushed
to disk before any further actions are taken.  On Unix, the directory
that contains the master journal is also synced in order to make sure
the master journal file will appear in the directory following a
power failure.</p>

<p>The purpose of the master journal is to ensure that multi-file
transactions are atomic across a power-loss.  But if the database files
have other settings that compromise integrity across a power-loss event
(such as [PRAGMA synchronous=OFF] or [PRAGMA journal_mode=MEMORY]) then
the creation of the master journal is omitted, as an optimization.

<br clear="both">
<tcl>hd_fragment multijrnlupdate</tcl>
<h3>5.3 Updating Rollback Journal Headers</h3>
<img src="images/ac/multi-2.gif" align="right" hspace="15">

<p>The next step is to record the full pathname of the master journal file
in the header of every rollback journal.  Space to hold the master
Changes to pages/changes.in.
15
16
17
18
19
20
21







22
23
24
25
26
27
28
<tcl>
set nChng 0
proc chng {date desc {options {}}} {
  global nChng aChng
  set aChng($nChng) [list $date $desc $options]
  incr nChng
}








chng {2016-02-15 (3.11.0)} {
<p><b>General improvements:</b>
<li>Enhanced [WAL mode] so that it works efficiently with transactions that are
    larger than the [cache_size].
<li>Added the [FTS5 detail option].
<li>Added the "EXTRA" option to [PRAGMA synchronous] that does a sync of the







>
>
>
>
>
>
>







15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<tcl>
set nChng 0
proc chng {date desc {options {}}} {
  global nChng aChng
  set aChng($nChng) [list $date $desc $options]
  incr nChng
}

chng {2016-04-00 (3.12.0)} {
<p><b>Performance enhancements:</b>
<li>Only create [master journal] files if two or more attached databases are
(1) modified, (2) do not have [PRAGMA synchronous] set to OFF, and (3)
(3) do not have the [journal_mode] set to OFF, MEMORY, or WAL.
}

chng {2016-02-15 (3.11.0)} {
<p><b>General improvements:</b>
<li>Enhanced [WAL mode] so that it works efficiently with transactions that are
    larger than the [cache_size].
<li>Added the [FTS5 detail option].
<li>Added the "EXTRA" option to [PRAGMA synchronous] that does a sync of the
Changes to pages/index.in.
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_11_0.html">Version 3.11.0</a>
of SQLite is recommended for all new development.
</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>







|







106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_12_0.html">Version 3.12.0</a>
of SQLite is recommended for all new development.
</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>
Changes to pages/tempfiles.in.
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
The shared-memory file has the same lifetime as its associated WAL file.
The shared-memory file is created when the WAL file is created and is
deleted when the WAL file is deleted.  During WAL file recovery, the
shared memory file is recreated from scratch based on the contents of
the WAL file being recovered.
</p>

<tcl>hd_fragment masterjrnl</tcl>
<h3>2.4 Master Journal Files</h3>

<p>
The master journal file is used as part of the atomic commit
process when a single transaction makes changes to multiple
databases that have been added to a single [database connection]
using the [ATTACH] statement.  The master journal file is always







|







197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
The shared-memory file has the same lifetime as its associated WAL file.
The shared-memory file is created when the WAL file is created and is
deleted when the WAL file is deleted.  During WAL file recovery, the
shared memory file is recreated from scratch based on the contents of
the WAL file being recovered.
</p>

<tcl>hd_fragment masterjrnl {master journal}</tcl>
<h3>2.4 Master Journal Files</h3>

<p>
The master journal file is used as part of the atomic commit
process when a single transaction makes changes to multiple
databases that have been added to a single [database connection]
using the [ATTACH] statement.  The master journal file is always
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238






















239
240
241
242
243
244
245
transaction commits when the master journal file is deleted.
See the documentation titled
<a href="atomiccommit.html">Atomic Commit In SQLite</a> for
additional detail.
</p>

<p>
The master journal file is only created in cases where a single
[database connection] is talking with two or more databases files
as a result of using [ATTACH] to connection to auxiliary databases,
and where a single transaction modifies more than one of those
database files.
Without the master journal, the transaction commit on a multi-database
transaction would be atomic for each database individually, but it
would not be atomic across all databases.  In other words, if the
commit were interrupted in the middle by a crash or power loss, then
the changes to one of the databases might complete while the changes
to another database might roll back.  The master journal causes all
changes in all databases to either rollback or commit together.
</p>























<tcl>hd_fragment stmtjrnl</tcl>
<h3>2.5 Statement Journal Files</h3>

<p>
A statement journal file is used to rollback partial results of
a single statement within a larger transaction.  For example, suppose







<
<
<
<
<








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







219
220
221
222
223
224
225





226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
transaction commits when the master journal file is deleted.
See the documentation titled
<a href="atomiccommit.html">Atomic Commit In SQLite</a> for
additional detail.
</p>

<p>





Without the master journal, the transaction commit on a multi-database
transaction would be atomic for each database individually, but it
would not be atomic across all databases.  In other words, if the
commit were interrupted in the middle by a crash or power loss, then
the changes to one of the databases might complete while the changes
to another database might roll back.  The master journal causes all
changes in all databases to either rollback or commit together.
</p>

</p>
The master journal file is only created for [COMMIT] operations that
involve multiple database files where at least two of the databases 
meet all of the following requirements:
<ol>
<li>The database is modified by the transaction
<li>The [PRAGMA synchronous] setting is not OFF
<li>The [PRAGMA journal_mode] is not OFF, MEMORY, or WAL
</ol>
This means that SQLite transactions are not atomic
across multiple database files on a power-loss when the database 
files have synchronous turned off or when they are using journal 
modes of OFF, MEMORY, or WAL.  For synchronous OFF and for
journal_modes OFF and MEMORY, database will usually corrupt if
a transaction commit is interrupted by a power loss.  For 
[WAL mode], individual database files are updated atomically
across a power-loss, but in the case of a multi-file transactions,
some files might rollback while others roll forward after
power is restored.
</p>


<tcl>hd_fragment stmtjrnl</tcl>
<h3>2.5 Statement Journal Files</h3>

<p>
A statement journal file is used to rollback partial results of
a single statement within a larger transaction.  For example, suppose