Documentation Source Text

<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

<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

<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

<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

</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>

</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>

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
................................................................................
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

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
................................................................................
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