Documentation Source Text

    database contents.

  <p>
    The following two sub-sections describe the specific ways in which 
    SQLite achieves this for single and multiple database transactions.

  [h3 "Single Database Transactions" single_db_transactions]

  <p>
    In order to atomically modify the database image stored in the 
    file-system from database image A to database image B, the file-system must
    first be manipulated to a state where it contains the database image A,
    but can by a single atomic operation be modified to contain database 
    image B. A file-system state that has the following properties satisfies
    this requirement:

  <ol>
    <li> The database file contains database image B.
    <li> There exists a valid journal file.
    <li> The first header of the journal file contains the page-size and 
         number of pages in database image A.
    <li> The journal file contains a valid journal record for each page of
         of database image A that either does not exist in database image B
         (because image B is smaller than image A), or does exist but has
         different content in database image B than it does in database 
         image A.
  </ol>

  <p>
    In this state, the file-system contains database image A. However, if the
    journal file is somehow made invalid, then the file-system will then
    contain database image B. There are several possibilities for IO 
    operations that will cause the journal file to become invalid, for 
    example:

  <ul>
    <li> Deleting the journal file from the file-system, or
    <li> Truncating the journal file to zero bytes in size, or
    <li> Overwriting some or all of the first 8 bytes in the journal file
         so that the journal file no longer contains a well-formed journal
         header.
  </ul>

  <p>
    Figure <cite>figure_filesystem2</cite> depicts an interim file-system
    state that may be used when committing a transaction that replaces
    an initial database image that consists of 4 pages of page-size bytes each
    with a database image that consists of 3 pages, also of page-size bytes
    each. The contents of the initial database image pages are A, B, C and
    D respectively. The final database image content is A, E and C. As 
    depicted, the file-system contains the initial database image, ABCD.
    However, if the journal file were to be somehow invalidated, then the 
    file-system would contain the final database image, AEC.

    [Figure filesystem2.gif figure_filesystem2 "Interim file-system state"]


  [h3 "Multiple Database Transactions" multi_db_transactions]


[h1 "SQLite Interoperabilty Requirements" locking_protocol]

[h1 References]

  <table id="refs" style="width:auto; margin: 1em 5ex">
    <tr><td style="width:5ex" id="ref_comer_btree">\[1\]<td>
     Douglas Comer, <u>Ubiquitous B-Tree</u>, ACM Computing Surveys (CSUR),
     v.11 n.2, pages 121-137, June 1979.