Documentation Source Text

#            <t*l>fileformat_import_requirement H00000</t*l>
#
unset -nocomplain ffreq
hd_read_requirement_file $::DOC/req/hlr30000.txt ffreq
proc fileformat_import_requirement {reqid} {
  return [lindex $::ffreq($reqid) 1]
}
proc fileformat_import_requirement2 {reqid} {
  return "<p class=req id=$reqid>[fileformat_import_requirement $reqid]</p>"
}
###############################################################################

catch { array unset ::SectionNumbers }
set ::SectionNumbers(1) 0
set ::SectionNumbers(2) 0
set ::SectionNumbers(3) 0
set ::SectionNumbers(fig) 0

          [fileformat_import_requirement H31410]
    <p class=req id=H31420>
          [fileformat_import_requirement H31420]

[h1 "Database File-System Representation" file_system_usage]

    <p>
      The previous section, section <cite>database_file_format</cite> 
      describes the format of an SQLite <i>database image</i>. A <i>database
      image</i> is the serialized form of a logical SQLite database. Normally,
      a <i>database image</i> is stored within the file-system in a single
      file, a <i>database file</i>. In this case no other data is stored
      within the <i>database file</i>, the first byte of the <i>database
      file</i> is the first byte of the <i>database image</i>, and the last 
      byte of the <i>database file</i> is the last byte of the <i>database 
      image</i>. For this reason, SQLite is often described as a "single-file 
      database system", implying that the contents of a database are always 
      stored in a single file within the file-system. However, this is not
      always the case. It is also possible for an SQLite <i>database image</i>
      to be distributed between the <i>database file</i> and a 
      <i>journal file</i>. A third file, a <i>master-journal file</i> may
      also be part of the file-system representation. Although a
      <i>master-journal file</i> never contains any part of the <i>database
      image</i>, it can contain meta-data that helps determine which parts of 
      the <i>database image</i> are stored within the <i>database file</i>, and
      which parts are stored within the <i>journal file</i>.

    <p>
      In other words, the file-system representation of an SQLite database
      consists of the following:

    <ul>
      <li> <p>A main <b>database file</b>. The <i>database file</i> is
           always present. It may be zero bytes in size, but it is always
           present.
           
      <li> <p>Optionally, a <b>journal file</b>. If present, the <i>journal
           file</i> is stored in the same file-system directory as the
           <i>database file</i>. The name of the <i>journal file</i> is the
           same as that of the database file with the string "-journal"
           appended to it.

      <li> <p>Optionally, a <b>master-journal file</b> may also be part of the
           file-system representation of a database image. A master-journal
           file may only be part of the representation if the journal file 
           is present. A <i>master-journal file</i> may be located anywhere
           within the file-system and may take any name. If present, the
           <i>master-journal</i> is identified by the <i>master-journal
           pointer</i> stored in the <i>journal file</i> (see section
           <cite>master_journal_ptr</cite> for details).
    </ul>

    <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 
      description of the various ways a <i>database image</i> may be
      distributed between the <i>database file</i> and <i>journal file</i>, 
      and the rules that must be followed to extract it. In other words, a 
      description of how SQLite or compatible software reads the <i>database 
      image</i> from the file-system.

    <p>
      Sub-section <cite>writing_to_files</cite> describes the guidelines that
      must be followed by SQLite or compatible software to safely modify the
      contents of an SQLite database within the file-system. These techniques
      allow a complex set of modifications to be made to the database image
      atomically, eliminating the risk of database corruption due to 
      application, Operating System (OS) or power failure while updating the
      database.

[h2 "Journal File Formats" journal_file_formats]

[h3 "Journal File Details" journal_file_format]

    <p>
      This section describes the format used by an SQLite <i>journal file</i>.

    <p>

    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.

    [fileformat_import_requirement2 H35030]
    [fileformat_import_requirement2 H35040]
    [fileformat_import_requirement2 H35050]
    [fileformat_import_requirement2 H35060]

  <p>
    The following requirements dictate the way in which the data for each
    page of the <i>database image</i> can be located within the file-system
    by a database reader.

    [fileformat_import_requirement2 H35070]
    [fileformat_import_requirement2 H35080]

[h2 "Writing to an SQLite Database" writing_to_files]

  <p>
    When an SQLite user commits a transaction that modifies the contents
    of the database, the database representation on disk must be modified
    to reflect the new contents of the database. SQLite is required to do

HLR H31420
For each page that is not a root page but is a part of a B-Tree tree
structure (not part of an overflow chain), the page type of the
corresponding pointer-map entry is set to the value 0x05 and the parent
page number field is set to the page number of the parent node in the
B-Tree structure.



HLR H35000
If a <i>journal file</i> contains a well-formed <i>master-journal 
pointer</i>, and the named <i>master-journal file</i> either does
not exist or does not contain the name of the <i>journal file</i>,
then the <i>journal file</i> shall be considered invalid.

HLR H35010
If the first 28 bytes of a <i>journal file</i> do not contain a well-formed
<i>journal header</i>, then the <i>journal file</i> shall be considered
invalid.

HLR H35020
If the journal file exists within the file-system and neither H35000 nor 
H35010 apply, then the journal file shall be considered valid.



HLR H35030
If there exists a valid <i>journal file</i> in the file-system, then the
database <i>page-size</i> in bytes used to interpret the <i>database image</i>
shall be the value stored as a 4-byte big-endian unsigned integer at byte
offset 24 of the <i>journal file</i>.

HLR H35040
If there exists a valid <i>journal file</i> in the file-system, then the
number of pages in the <i>database image</i> shall be the value stored as 
a 4-byte big-endian unsigned integer at byte offset 24 of the 
<i>journal file</i>.



HLR H35050
If there is no valid <i>journal file</i> in the file-system, then the
database <i>page-size</i> in bytes used to interpret the <i>database image</i>
shall be the value stored as a 2-byte big-endian unsigned integer at byte
offset 16 of the <i>database file</i>.

HLR H35060
If there is no valid <i>journal file</i> in the file-system, then the
number of pages in the <i>database image</i> shall be calculated by dividing
the size of the <i>database file</i> in bytes by the database <i>page-size</i>.


HLR H35070
If there exists a valid <i>journal file</i> in the file-system, then the
contents of each page of the <i>database image</i> for which there is a valid
<i>journal record</i> in the <i>journal file</i> shall be read from the
corresponding journal record.

HLR H35080
The contents of all <i>database image</i> pages for which there is no valid
<i>journal record</i> shall be read from the database file.