Documentation Source Text

</tr>
<tr>
<td>14..15</td><td>szPage</td>
<td>The database page size in bytes, or 1 if the page size is 65536.
</tr>
<tr>
<td>16..19</td><td>mxFrame</td>
<td>Number of valid frames in the WAL file.
</tr>
<tr>
<td>20..23</td><td>nPage</td>
<td>Size of the database file in pages.
</tr>
<tr>
<td>24..31</td><td>aFrameCksum</td>
................................................................................
</tr>
</table>
</center>

<tcl>hd_fragment mxframe mxFrame</tcl>
<h3>The mxFrame field</h3>

<p>The 32-bit unisgned integer at offset 16 (and repeated at offset 64)
is the number of valid frames in the WAL.




<p>
When this field is zero, it indicates that the WAL is empty and that
all content should be obtained directly from the database file.
<p>
When mxFrame is equal to [nBackfill], that indicates that all content
in the WAL has been written back into the database.
In that case, all content can be read directly from the database.
Furthermore, the next writer is free to [reset the WAL] if no other
connections are holding locks on WAL_READ_LOCK(N) for N>0.
<p>
The mxFrame value is always greater than or equal to both
[nBackfill] and nBackfillAttempted.


<tcl>hd_fragment nbackfill nBackfill</tcl>
<h3>The nBackfill field</h3>
................................................................................
If the WAL and WAL-index files are missing, then a process that
lacks permission to create and initialize those files will not be
able to open the database, unless the database is designated
as immutable using the [immutable query parameter].

<li><p><b>Reconstruct the global shared WAL-index during [recovery]</b>






<li><p><b>Append a new transaction to the end of the WAL</b>




<li><p><b>Read content from the database and WAL as part of a transaction</b>

<li><p><b>Run a checkpoint</b>

<li><p><b>Reset the WAL file</b>







</ul>

<tcl>hd_fragment recovery recovery {WAL-mode crash recovery}</tcl>
<h1>Crash Recovery</h1>

<p>
After an application crash, or a system crash, or a power failure, the
database might be left in an inconsistent state.  When that happens,
the first connection to the database will need to run a recovery
procedure to restore the database to a consistent state before it begins
using the database.  This section describes that procedure.



<p><i>TBD...</i></p>

</tr>
<tr>
<td>14..15</td><td>szPage</td>
<td>The database page size in bytes, or 1 if the page size is 65536.
</tr>
<tr>
<td>16..19</td><td>mxFrame</td>
<td>Number of valid and committed frames in the WAL file.
</tr>
<tr>
<td>20..23</td><td>nPage</td>
<td>Size of the database file in pages.
</tr>
<tr>
<td>24..31</td><td>aFrameCksum</td>
................................................................................
</tr>
</table>
</center>

<tcl>hd_fragment mxframe mxFrame</tcl>
<h3>The mxFrame field</h3>

<p>The 32-bit unsigned integer at offset 16 (and repeated at offset 64)
is the number of valid frames in the WAL.  Because WAL frame are numbered
starting with 1, mxFrame is also the index of the last valid commit frame
in the WAL. A commit frame is a frame that has a non-zero "size of database"
value in bytes 4 through 7 of the frame header, and that indicates the end
of a transaction.
<p>
When mxFrame field is zero, it indicates that the WAL is empty and that
all content should be obtained directly from the database file.
<p>
When mxFrame is equal to [nBackfill], that indicates that all content
in the WAL has been written back into the database.
In that case, all content can be read directly from the database.
Furthermore, the next writer is free to [reset the WAL] if no other
connections hold locks on WAL_READ_LOCK(N) for N>0.
<p>
The mxFrame value is always greater than or equal to both
[nBackfill] and nBackfillAttempted.


<tcl>hd_fragment nbackfill nBackfill</tcl>
<h3>The nBackfill field</h3>
................................................................................
If the WAL and WAL-index files are missing, then a process that
lacks permission to create and initialize those files will not be
able to open the database, unless the database is designated
as immutable using the [immutable query parameter].

<li><p><b>Reconstruct the global shared WAL-index during [recovery]</b>

<p>All of the WAL-index locks, except for WAL_READ_LOCK(0),
are held exclusively while reconstructing the global shared WAL-index
during [recovery].  


<li><p><b>Append a new transaction to the end of the WAL</b>

<p>An exclusive lock is held on WAL_WRITE_LOCK while adding new
frame onto the end of a WAL file.  

<li><p><b>Read content from the database and WAL as part of a transaction</b>

<li><p><b>Run a checkpoint</b>

<li><p><b>Reset the WAL file</b>

<p>A [WAL reset] means to rewind the WAL and start adding new frames
at the beginning.  This occurs while appending new frames to a WAL
that has [mxFrame] equal to [nBackfill] and which has no locks on
WAL_READ_LOCK(1) through WAL_READ_LOCK(4).  The WAL_WRITE_LOCK is
held.

</ul>

<tcl>hd_fragment recovery recovery {WAL-mode crash recovery}</tcl>
<h1>Recovery</h1>

<p>





Recovery is the process of rebuilding the WAL-index so that it is
synchronized with the WAL.


<p>
Recovery is run by the first thread to connect to a WAL-mode database.
Recovery restores the WAL-index so that it accurately describes the
WAL file.  If there is no WAL file present when the first thread connects
to the database, there is nothing to recover, but the recovery process
still runs to initialize the WAL-index.

<p>
If the WAL-index is implemented as a memory-mapped file and that file is
read-only to the first thread to connect, then that thread creates an
private heap-memory ersazt WAL-index and runs the recovery routine to
populate that private WAL-index.  The same data results, but it is held
privately rather that being written into the public shared memory area.

<p>
Recovery works by doing a single pass over the WAL, from beginning to end.
The checksums are verified on each frame of the WAL as it is read.  The
scan stops at the end of the file or at the first invalid checksum.
The [mxFrame] field is set to the index of the last valid commit frame
in WAL.  Since WAL frame numbers are indexed starting with 1, mxFrame is
also the number of valid frames in the WAL.  A "commit frame" is a frame
that has a non-zero value in bytes 4 through 7 of the frame header.
Since the recovery procedure has no way of knowing how many frames of the
WAL might have previously been copied back into the database, it initializes
the [nBackfill] value to zero.

<p>
During recovery of the global shared-memory WAL-index, exclusive locks are
held on WAL_WRITE_LOCK, WAL_CKPT_LOCK, WAL_RECOVER_LOCK, and WAL_READ_LOCK(1) through WAL_READ_LOCK(4).  In other words, all locks associated with the
WAL-index except for WAL_READ_LOCK(0) are held exclusively.  This prevents
any other thread from writing the database and from reading any transactions
that are held in the WAL, until the recovery is complete.