Documentation Source Text

     table of contents, figure numbering and internal references (section
     numbers and hyper-links.
  </b>
</div>
<!-- End of standard rt docs header -->

<h1>Document Overview</h1>
  <h2>Scope and Purpose</h2>

    <p>

      The <i>SQLite File Database File Format</i> document
      <cite>ff_sqlitert_requirements</cite> contains a description of the 
      serialized format used to store an SQLite database 
      <span class=todo>ref</span>. This document describes, in detail, 
      the methods used by SQLite to safely read and modify a database 
      file stored in a file-system.

    <p>
      SQLite does not interact directly with the host operating system that
      provides the file-system service. Instead, the user is required to
      supply an adaptor component that implements the <i>SQLite Virtual
      File System</i> interface (described in
      <cite>capi_sqlitert_requirements</cite>) used by SQLite. The adaptor
      component is responsible for translating the calls made by SQLite to the
      calls to the operating system specific interface provided to access the
      file-system service.




    <center><img src="images/fileformat/vfs_role.gif">
    <p><i>Figure <span class=fig id=figure_vfs_role></span> - Virtual File System (VFS) Adaptor</i>
      </center>

    <p>
      The descriptions in this document are of the way that SQLite invokes the
      <i>VFS API</i> provided by the adaptor component depicted in figure
      <cite>figure_vfs_role</cite>.








  <h2>Document Organization</h2>
  <h2>Glossary</h2>
































    <p class=todo>
      After this document is ready, make the vocabulary consistent and
      then add a glossary here.


    <ul>










      <li>xFileControl





      <li>xDeviceCharacteristics
      <li>xSectorSize
      <li>xAccess
      <li>xOpen
      <li>xFullPathname

      <li>xClose

    </ul>






<h1>VFS Adaptor Related Assumptions</h1>

  <h2>SQLite File-System Usage </h2>
    <p>
      SQLite uses the file-system service made available via the 
      <i>VFS adaptor</i> to create, read and modify three different types
      of files, as follows:
................................................................................
      <li> journal files, and
      <li> master journal files.
    </ul>

    <p>
      A database file is a file-system file used to store an SQLite database 
      image (see <cite>ff_sqlitert_requirements</cite>).



  <h2 id=fs_characteristics>System Failure Related Assumptions</h2>
    <p>
      In the event of an operating system or power failure, the various 
      combinations of file-system and storage hardware available provide
      varying levels of guarantee as to the integrity of the data written
      to the file system just before or during the failure. The exact
................................................................................
      crash occured.

    <p>
      Assuming that any and all sectors in the transient state may be 
      corrupted following a power or system failure is a very pessimistic
      approach. Some modern systems provide more sophisticated guarantees
      than this. SQLite allows the VFS implementation to specify at runtime
      that the current platform supports one or more of the following 
      properties:

    <ul>
      <li><p>The <b>safe-append</b> property. If a system supports the
          <i>safe-append</i> property, it means that when a file is extended
          the new data is written to the persistent media before the size
          of the file itself is updated. This guarantees that if a failure

     table of contents, figure numbering and internal references (section
     numbers and hyper-links.
  </b>
</div>
<!-- End of standard rt docs header -->

<h1>Document Overview</h1>


  <p>
    SQLite stores an entire database within a single file, the format of
    which is described in the <i>SQLite File Database File Format</i> 
    document <cite>ff_sqlitert_requirements</cite>. Each database file is

    stored within a file system, presumably provided by the host operating
    system. Instead of interfacing with the operating system directly, 





    the host application is required to supply an adaptor component that 
    implements the <i>SQLite Virtual File System</i> interface 
    (described in <cite>capi_sqlitert_requirements</cite>). The adaptor
    component is responsible for translating the calls made by SQLite to


    the <i>VFS</i> interface into calls to the file-system interface 
    provided by the operating system. This arrangement is depicted in figure
    <cite>figure_vfs_role</cite>.
  
    <center><img src="images/fileformat/vfs_role.gif">
    <p><i>Figure <span class=fig id=figure_vfs_role></span> - Virtual File System (VFS) Adaptor</i>
      </center>

  <p>



    Although it would be easy to design a system that uses the <i>VFS</i>
    interface to read and update the content of a database file stored
    within a file-system, there are several complicated issues that need
    to be addressed by such a system:

  <ol>
    <li><p>SQLite is required to <b>implement atomic and durable
	transactions</b> (the 'A' and 'D' from the ACID acronym), even if an
	application, operating system or power failure occurs midway through or
        shortly after updating a database file.

	<p>To implement atomic transactions in the face of potential 
	application, operating system or power failures, database writers write
	a copy of those portions of the database file that they are going to
	modify into a second file, the <i>journal file</i>, before writing
        to the database file. If a failure does occur while modifying the 
        database file, SQLite can reconstruct the original database 
        (before the modifications were attempted) based on the contents of 
        the <i>journal file</i>.

    <li><p>SQLite is required to <b>implement isolated transactions</b> (the 'I'
        from the ACID acronym). 

	<p>This is done by using the file locking facililities provided by the
	VFS adaptor to serialize writers (write transactions) and preventing
	readers (read transactions) from accessing database files while writers
        are midway through updating them.

    <li><p>For performance reasons, it is advantageous to <b>minimize the 
        quantity of data read and written</b> to and from the file-system.

        <p>As one might expect, the amount of data read from the database 
        file is minimized by caching portions of the database file in main 
        memory. Additionally, multiple updates to the database file that
        are part of the same <i>write transaction</i> may be cached in
        main memory and written to the file periodically, allowing for
        more efficient IO patterns and eliminating the redundant write 
        operations that could take place if part of the database file is
        modified more than once within a single <i>write transaction</i>.

  </ol>

  <p class=todo>


    System requirement references for the above points.


  <p>
    This document describes in detail the way that SQLite uses the API 
    provided by the VFS adaptor component to solve the problems and implement
    the strategies enumerated above. It also specifies the assumptions made
    about the properties of the system that the VFS adaptor provides
    access to. For example, specific assumptions about the extent of
    data corruption that may occur if a power failure occurs while a
    database file is being updated are presented in section 
    <cite>fs_characteristics</cite>.


  <p>
    This document does not specify the details of the interface that must
    be implemented by the VFS adaptor component, that is left to
    <cite>capi_sqlitert_requirements</cite>.
    









  <h2>Document Organization</h2>
  <h2>Glossary</h2>
    <p class=todo>
      After this document is ready, make the vocabulary consistent and
      then add a glossary here.

<h1>VFS Adaptor Related Assumptions</h1>

  <h2>SQLite File-System Usage </h2>
    <p>
      SQLite uses the file-system service made available via the 
      <i>VFS adaptor</i> to create, read and modify three different types
      of files, as follows:
................................................................................
      <li> journal files, and
      <li> master journal files.
    </ul>

    <p>
      A database file is a file-system file used to store an SQLite database 
      image (see <cite>ff_sqlitert_requirements</cite>).

  <h2>Performance Related Assumptions</h2>

  <h2 id=fs_characteristics>System Failure Related Assumptions</h2>
    <p>
      In the event of an operating system or power failure, the various 
      combinations of file-system and storage hardware available provide
      varying levels of guarantee as to the integrity of the data written
      to the file system just before or during the failure. The exact
................................................................................
      crash occured.

    <p>
      Assuming that any and all sectors in the transient state may be 
      corrupted following a power or system failure is a very pessimistic
      approach. Some modern systems provide more sophisticated guarantees
      than this. SQLite allows the VFS implementation to specify at runtime
      that the current platform supports zero or more of the following 
      properties:

    <ul>
      <li><p>The <b>safe-append</b> property. If a system supports the
          <i>safe-append</i> property, it means that when a file is extended
          the new data is written to the persistent media before the size
          of the file itself is updated. This guarantees that if a failure