Documentation Source Text

    <p>
      Usually, a <i>database image</i> is stored entirely within the <i>database
      file</i>. Other configurations, where the <i>database image</i> data
      is distributed between the <i>database file</i> and its <i>journal
      file</i>, are used as interim states when modifying the contents of
      the <i>database image</i> to commit a database transaction.


    <p>
      Sub-section <cite>journal_file_formats</cite> describes the formats 
      used by <i>journal</i> and <i>master-journal</i> files.

    <p>
      Sub-section <cite>reading_from_files</cite> contains a precise 
................................................................................

    <p>
      The set of <i>journal records</i> that follow a <i>journal header</i>
      in a <i>journal file</i> are packed tightly together. There are no
      alignment requirements for <i>journal records</i> as there are for
      <i>journal headers</i>.

  [h4 "Master Journal Pointer"]

    <p>
      To support <i>atomic</i> transactions that modify more than one 
      database file, SQLite sometimes includes a <i>master journal pointer</i>
      record in a <i>journal file</i>. A <i>master journal pointer</i>
      contains the name of a <i>master journal-file</i> along with a 
      check-sum and some well-known values that allow the 
................................................................................
               first 8 bytes of a <i>journal header</i>. The well-known
               sequence of bytes is:
                 <pre>0xd9 0xd5 0x05 0xf9 0x20 0xa1 0x63 0xd7</pre>
    </table>

[h3 "Master-Journal File Details" masterjournal_file_format]








[h2 "Reading an SQLite Database" reading_from_files]

  <p>
    As described in section <cite>pages_and_page_types</cite> of this document,
    an SQLite database image is a set of contiguously numbered fixed size 
    pages. The numbering starts at 1, not 0. Page 1 contains the 
    <i>database file header</i> and the root page of the <i>schema table</i>, 
    and all other pages within the database image are somehow referred to 
    by number from page 1, either directly or indirectly.


    






  <p>
    Usually, the <i>database file</i> contains the complete, unadulterated 
    <i>database image</i>. When this is the case, the file offset of each 
    database page can be calculated based on its page number. Reading the






    contents of a <i>database page</i> is a simple matter of reading a
    block of <i>page-size</i> bytes from the calculated offset. However, if 



    there is a <i>journal file</i> corresponding to the <i>database file</i>
    present within the file-system then the situation can be more 

























    complicated. The current data for each page of the <i>database image</i>

    may currently be stored within the <i>database file</i> at a file offset
    based on its page number as it normally is, or the current version of
    the data may be stored somewhere within the <i>journal file</i>.



  <p>
    These requirements describe the way a database reader must determine
    whether or not there is a valid <i>journal file</i> within the 
    file-system.

    [fileformat_import_requirement2 H35000]
    [fileformat_import_requirement2 H35010]
    [fileformat_import_requirement2 H35020]






  <p class=todo>Requirements for determining the validity of records.

  <p>
    The following requirements dictate the way in which database
    <i>page-size</i> and the number of pages in the <i>database image</i>
    should be determined by the reader.

    <p>
      Usually, a <i>database image</i> is stored entirely within the <i>database
      file</i>. Other configurations, where the <i>database image</i> data
      is distributed between the <i>database file</i> and its <i>journal
      file</i>, are used as interim states when modifying the contents of
      the <i>database image</i> to commit a database transaction.


    <p>
      Sub-section <cite>journal_file_formats</cite> describes the formats 
      used by <i>journal</i> and <i>master-journal</i> files.

    <p>
      Sub-section <cite>reading_from_files</cite> contains a precise 
................................................................................

    <p>
      The set of <i>journal records</i> that follow a <i>journal header</i>
      in a <i>journal file</i> are packed tightly together. There are no
      alignment requirements for <i>journal records</i> as there are for
      <i>journal headers</i>.

  [h4 "Master Journal Pointer" master_journal_ptr]

    <p>
      To support <i>atomic</i> transactions that modify more than one 
      database file, SQLite sometimes includes a <i>master journal pointer</i>
      record in a <i>journal file</i>. A <i>master journal pointer</i>
      contains the name of a <i>master journal-file</i> along with a 
      check-sum and some well-known values that allow the 
................................................................................
               first 8 bytes of a <i>journal header</i>. The well-known
               sequence of bytes is:
                 <pre>0xd9 0xd5 0x05 0xf9 0x20 0xa1 0x63 0xd7</pre>
    </table>

[h3 "Master-Journal File Details" masterjournal_file_format]

  <p>
    A <i>master-journal file</i> contains the full paths to two or more
    <i>journal files</i>, each encoded using UTF-8 encoding and terminated
    by a single nul character (byte value 0x00). There is no padding 
    between the journal paths, each UTF-8 encoded path begins immediately
    after the nul character that terminates the previous one.

[h2 "Reading an SQLite Database" reading_from_files]

  <p>
    As described in section <cite>pages_and_page_types</cite> of this document,
    an SQLite database image is a set of contiguously numbered fixed size 
    pages. The numbering starts at 1, not 0. Page 1 contains the 
    <i>database file header</i> and the root page of the <i>schema table</i>, 
    and all other pages within the database image are somehow referred to 
    by number from page 1, either directly or indirectly. In order to be able
    to read the <i>database image</i> from within the file-system, a database
    reader needs to be able to ascertain:

  <ol>
    <li> The <i>page-size</i> used by the database image,
    <li> The number of pages in the <i>database image</i>, and
    <li> The content of each database page.
  </ol>

  <p>
    Usually, the <i>database file</i> contains the complete, unadulterated 


    <i>database image</i>. In this case, reading the <i>database image</i> is 
    straightforward. The <i>page-size</i> used by the database image can be
    read from the 2-byte big-endian integer field stored at byte offset 16 of
    the database file (see section <cite>file_header). The number of pages in
    the <i>database image</i> can be determined by querying the size of
    the database file in bytes and then dividing by the <i>page-size</i>.
    Reading the contents of a <i>database page</i> is a simple matter of 
    reading a block of <i>page-size</i> bytes from an offset calculated from
    the page-number of the required page.
    
  <p>
    However, if there is a valid <i>journal file</i> corresponding to the 
    <i>database file</i> present within the file-system then the situation 
    is more complicated. The file-system is considered to contain a valid 
    <i>journal file</i> if each of the following conditions are met:

  <ul>
    <li> A <i>journal file</i> is present in the file system.
    <li> The <i>journal file</i> either does not end with a well-formed 
         <i>master-journal pointer</i> (see section 
         <cite>master_journal_ptr</cite>) or the <i>master-journal file</i> 
         referred to by the <i>master-journal pointer</i> is present in
         the file-system.
    <li> The first 28 bytes of the <i>journal file</i> contain a 
         well-formed <i>journal header</i> (see section
         <cite>journal_header_format</cite>).  
  </ul>

  <p>
    If the file system contains a valid <i>journal file</i>, then the
    <i>page-size</i> used by and the number of pages in the <i>database
    image</i> are stored in the first <i>journal header</i> of the 
    <i>journal file</i>. Specifically, the page-size is stored as a 4-byte
    big-endian unsigned integer at byte offset 24 of the journal file, and the
    number of pages in the database image is stored as a 4-byte big-endian
    unsigned integer at byte offset of 16 of the same file.
    
  <p>
    The current data for each page of the 
    <i>database image</i>
    may be stored within the <i>database file</i> at a file offset
    based on its page number as it normally is, or the current version of
    the data may be stored somewhere within the <i>journal file</i>.

    [Figure filesystem1.gif figure_filesystem1 "Two ways to store the same database image"]

  <p>
    These requirements describe the way a database reader must determine
    whether or not there is a valid <i>journal file</i> within the 
    file-system.

    [fileformat_import_requirement2 H35000]
    [fileformat_import_requirement2 H35010]
    [fileformat_import_requirement2 H35020]

  <p>
    If there is a valid <i>journal file</i> within the file-system, the 
    following requirements govern how a reader should determine the set
    of valid <i>journal records</i> that it contains.

  <p class=todo>Requirements for determining the validity of records.

  <p>
    The following requirements dictate the way in which database
    <i>page-size</i> and the number of pages in the <i>database image</i>
    should be determined by the reader.