Documentation Source Text

    any method may be used by an SQLite database writer to update the database
    file-system representation. SQLite itself uses the "rollback-journal method"
    described in section <cite>rollback_journal_method</cite>. For this reason,
    section <cite>rollback_journal_method</cite> contains numbered requirements
    but section <cite>rollforward_journal_method</cite> does not.

  [h3 "The Rollback-Journal Method" rollback_journal_method]

    <p>
      This section describes the method used by SQLite to update a database 
      image within a database file-system representation. This is one way
      to modify a database image in accordance with the requirements in the
      parent section. When overwriting database image A with database image B 
      using this method, assuming that to begin with database image A is 
      entirely contained within the database file and that the page-size of
      database image B is the same as that of database image A, the following 
      steps are taken:

    <ol>
      <li> <p>The start of the journal file is populated with data that is not
           a valid journal header.
      <li> <p>For each page in database image A that is not a free-list leaf 
           page and either does not exist in database image B or exists but
           is populated with different content, a record is written to the
           journal file. The record contains a copy of the original database
           image A page.
      <li> <p>The journal file is populated with a valid journal header. The
           page-count field of the journal header is set to the number of
           pages in database image A. The record-count is set to the number
           of records written to the journal file in step 2.
      <li> <p>The content of each page of database image B that is either not
           present or populated differently in database image A is copied
           into the database file. If database image B is smaller than database
           image A, the database file is truncated to the size required by
           database image B.
      <li> <p>One of several file-system operations that cause the journal file
           to become invalid is performed. For example:
           <ul>
             <li>The journal file is deleted from the file-system, or
             <li>The journal file is truncated to zero bytes in size, or
             <li>Some or all of the first 8 bytes of the journal file are
                 overwritten so that the journal file no longer begins with 
                 a well-formed journal header (and is therefore not valid).
           </ul>
    </ol>

    <p>
      During steps 1 and 2 of the above procedure, the database file-system 
      representation clearly contains database image A. The database file
      itself has not been modified, and the journal file is not valid (since
      it does not begin with a valid journal file header). Following step 3,
      the database file-system representation still contains database image
      A. The number of pages in the database image and the content of some
      pages now resides in the journal file, but the database image remains
      unchanged. During and following step 4, the current database image is
      still database image A. Although some or all of the pages in the 
      database file may have been overwritten or truncated away, a valid 
      journal records containing the original database image A data exists
      for all such pages that were not free-list leaf pages in database 
      image A. And although the size of the database file may have been
      modified, the size of the current database image, database image A, 
      is stored in the journal header.

    <p>
      Once step 5 of the above procedure is performed, the database file-system
      representation contains database image B. The journal file is no longer
      valid, so the database image consists of the contents of the database
      file, database image B.
  <p>
    Figure <cite>figure_filesystem2</cite> depicts a possible interim state 
    of the database file-system representation used while committing a transaction
    that replaces a four page database image with a three page database image.
    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. The intermim state depicted
    is that reached at the end of step 4 in the above procedure. In this state, 
    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 used to atomically overwrite database image ABCD with AEC"]

    <p class=todo>
      The above does not explain multiple header journals. Or multi-file 
      transactions.

    <p class=todo> FINISH THIS!

  [h4 "Multiple Database Transactions" multi_db_transactions]

<!--




  <p>
    SQLite is required 
    to do make all modifications associated with the transaction such that 
    the database image is modified atomically. If an application, OS or 
    power failure occurs while SQLite is updating the database, upon recovery 
    the contents of the database must reflect either that all modifications 
    associated with the database transaction were successfully applied, or 

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


















  [h4 "Multiple Database Transactions" multi_db_transactions]

  <p class=todo>
    Deleting the master-journal is used as the atomic operation.
-->

  [h3 "The Atomic-Write Method" atomic_write_method]

    <p class=todo>
      Describe the special atomic-write option.

  [h3 "The Rollforward-Journal Method" rollforward_journal_method]

    <p class=todo>
      Describe the how the journal file can also be used as a roll 
      forward journal or "transaction log". This section does not 
      contain requirements. It is only here to make the point that
      alternatives to the rollback journal method exist.


[h1 "SQLite Interoperabilty Requirements" interoperability_requirements]

  [h2 "SQLite Locking Protocol" locking_protocol]

    <p>