fileformat.html

sqlite3源码,适合作为嵌入式（embedded）

        page-size, user-cookie value etc.),

      <tr><td>Non-auto-vacuum database  <td>
        Any database that is not an auto-vacuum database. A non-auto-vacuum
        database contains no pointer-map pages and has a zero value stored
	in the 4-byte big-endian integer field at offset 52 of the database
        file header (section <cite>file_header</cite>).

      <tr><td>Overflow chain             <td>
        A linked list of overflow pages across which a single (large)
        database record is stored (see section 
        <cite>overflow_page_chains</cite>).

      <tr><td>Overflow page             <td>
        If a B-Tree cell is too large to store within a B-Tree page, a
	portion of it is stored using a chain of one or more overflow pages
        (see section <cite>overflow_page_chains</cite>).

      <tr><td>Pointer-map page          <td>
	A database page used to store meta data only present in auto-vacuum
        databases (see section <cite>pointer_map_pages</cite>).

      <tr><td>Right child page          <td>
        Each internal B-Tree node page has one or more child pages. The
        rightmost of these (the one containing the largest key values) is
        known as the right child page.

      <tr><td>Root page                 <td>
        A root page is a database page used to store the root node of a
        B-Tree data structure.

      <tr><td>Schema layer file format  <td>
	An integer between 1 and 4 stored as a 4 byte big-endian integer at
	offset 44 of the file header (section <cite>file_header</cite>).
	Certain file format constructions may only be present in databases
        with a certain minimum schema layer file format value.

      <tr><td>Schema table              <td>
	The table B-Tree with root-page 1 used to store database records
        describing the database schema. Accessible as the "sqlite_master" 
        table from within SQLite.

      <tr><td>Schema version            <td>
	A 32-bit integer field stored at byte offset 40 of the database file
	header (see section <cite>file_header</cite>). Normally, SQLite
        increments this value each time it modifies the databas schema.

      <tr><td>Table B-Tree              <td>
        One of two variants on the B-Tree data structure used within SQLite
        database files. A table B-Tree (section <cite>table_btrees</cite>)
        uses 64 bit integers as key values and stores an associated database
        record along with each key value.

      <tr><td>User cookie               <td>
	A 32-bit integer field stored at byte offset 60 of the database file
	header (see section <cite>file_header</cite>). Normally, SQLite
        increments this value each time it modifies the databas schema.

      <tr><td>Variable Length Integer   <td>
        A format used for storing 64-bit signed integer values in SQLite 
        database files. Consumes between 1 and 9 bytes of space, depending
        on the precise value being stored.

      <tr><td>Well formed database file <td>
        An SQLite database file that meets all the criteria laid out in
        section <cite>database_file_format</cite> of this document.
    </table>

<h1 id=sqlite_database_files>SQLite Database Files</h1>
 
  <p>
    The bulk of this document, section <cite>database_file_format</cite>,
    contains the definition of a <i>well-formed SQLite database file</i>.
    SQLite is required to create database files that meet this definition.

  <p class=req id=H30010>
          The system shall ensure that at the successful conclusion of a
database transaction the contents of the database file constitute
a <i>well-formed SQLite database file</i>.

  <p>
    Additionally, the database file should contain a serialized version
    of the logical database produced by the transaction. For all but the
    most trivial logical databases, there are many possible serial 
    representations.

  <p class=req id=H30020>
          The system shall ensure that at the successful conclusion of a
database transaction the contents of the database file are a valid
serialization of the contents of the logical SQL database produced
by the transaction.

<!--
  <p>
    Section <cite>database_file_manipulation</cite> contains requirements
    describing in more detail the way in which SQLite manipulates the
    fields and data structures described in section
    <cite>database_file_format</cite> under various circumstances. These
    requirements are to a certain extent derived from the requirements 
    in this section.
-->
  

<h1 id=database_file_format>Database File Format Details</h1>

  <p>
    This section describes the various fields and sub-structures that make up
    the format used by SQLite to serialize a logical SQL database. 
  <p>
    This section does not contain requirements governing the behaviour of any
    software system. Instead, along with the plain language description of the
    file format are a series of succinct, testable statements describing the
    properties of "well-formed SQLite database files".  Some of these
    statements describe the contents of the database file in terms of the
    contents of the logical SQL database that it is a serialization of. e.g.
    "For each SQL table in the database, the database file shall...".
    The contents and properties of a logical database
    include:
  <ul>
    <li>Whether or not the database is an auto-vacuum database, and if
        so whether or not incremental-vacuum is enabled,
    <li>The configured page-size of the database,
    <li>The configured text-encoding of the database,
    <li>The configured user-cookie value,
    <li>The set of database tables, indexs, triggers and views that make
        up the database schema and their properties, and
    <li>The data (rows) inserted into the set of database tables.
  </ul>

  <p class=todo>
    This concept of a logical database should be defined properly 
    in some requirements document so that it can be referenced from
    here and other places. The definition will be something like the
    list of bullet points above.

  <p>
    A well-formed SQLite database file is defined as a file for which
    all of the statements itemized as requirements within this section
    are true. <span class=todo>mention the requirements numbering scheme
    here.</span> A software system that wishes to interoperate with other
    systems using the SQLite database file format should only ever
    output well-formed SQLite databases. In the case of SQLite itself,
    the system should ensure that the database file is well-formed at
    the conclusion of each database transaction.

  <h2 id="fileformat_overview">File Format Overview</h2>
    <p>
      A B-Tree is a data structure designed for offline storage of a set of
      unique key values. It is structured so as to support fast querying 
      for a single key or range of keys. As implemented in SQLite, each
      entry may be associated with a blob of data that is not part of the
      key. For the canonical introduction to the B-Tree and its variants, 
      refer to reference <cite>ref_comer_btree</cite>. The B-Tree 
      implementation in SQLite also adopts some of the enhancements 
      suggested in <cite>ref_knuth_btree</cite>
    <p>
      An SQLite database file contains one or more B-Tree structures. Each
      B-Tree structure stores the data for a single database table or 
      index. Hence each database file contains a single B-Tree to store
      the contents of the <i>sqlite_master</i> table, and one B-Tree
      for each database table or index created by the user. If the database
      uses auto-increment integer primary keys, then the database file
      also contains a B-Tree to store the contents of the automatically 
      created <i>sqlite_sequence</i> table.
    <p>
      SQLite uses two distinct variants of the B-Tree structure. One variant,
      hereafter refered to as a "table B-Tree" uses signed 64-bit integer
      values for keys. Each entry has an associated variable length blob of 
      data used to store a database record (see section
      <cite>record_format</cite>). Each SQLite database file contains one 
      table B-Tree for the schema table and one table B-Tree for each
      additional database table created by the user.
    <p>
      A database record is a blob of data containing an ordered list of
      SQL values (integers, real values, NULL values, blobs or strings).
      For each row in each table at the SQL level, there is an 
      entry in the corresponding table B-Tree structure in the file. The
      entry key is same as the SQL "rowid" or "integer primary key" field
      of the table row. The associated database record is made up of the
      row's column values, in declaration (CREATE TABLE) order.
    <p>
      The other B-Tree variant used by SQLite, hereafter an "index B-Tree"
      uses database records (section <cite>record_format</cite>) as keys.
      For this kind of B-Tree, there is no additional data associated with
      each entry. SQLite databases contain an index B-Tree for each database
      index created by the user. Database indexes may be created by CREATE
      INDEX statements, or by UNIQUE or PRIMARY KEY (but not INTEGER PRIMARY
      KEY) clauses added to CREATE TABLE statements. 
    <p>
      Index B-Tree structures contain one entry for each row in the 
      associated table at the SQL level. The database record used as the
      key consists of the row's value for each of the indexed columns in
      declaration (CREATE INDEX) order, followed by the row's "rowid" or
      "integer primary key" column value.
    <p>
      For example, the following SQL script:
    <pre>
      CREATE TABLE t1(a INTEGER PRIMARY KEY, b, c, d);
      CREATE INDEX i1 ON t1(d, c);

      INSERT INTO t1 VALUES(1, 'triangle', 3, 180, 'green');
      INSERT INTO t1 VALUES(2, 'square',   4, 360, 'gold');
      INSERT INTO t1 VALUES(3, 'pentagon', 5, 540, 'grey');
      ...</pre>
    <p>
      Creates a database file containing three B-Tree structures: one table
      B-Tree to store the <i>sqlite_master</i> table, one table B-Tree to 
      store table "t1", and one index B-Tree to store index "i1". The
      B-Tree structures created for the user table and index are populated
      as shown in figure <cite>figure_examplepop</cite>.
      <center><img src="images/fileformat/examplepop.gif">
      <p><i>Figure <span class=fig id=figure_examplepop></span> - Example B-Tree Data.</i>
      </center>

  <h2>Global Structure</h2>
    <p>
      The following sections and sub-sections describe precisely the format
      used to house the B-Tree structures within an SQLite database file.

    <h3 id="file_header">File Header</h3>
      <p>
        Each SQLite database file begins with a 100-byte header. The header
        file consists of a well known 16-byte sequence followed by a series of
        1, 2 and 4 byte unsigned integers. All integers in the file header (as
        well as the rest of the database file) are stored in big-endian format.
        
      <p>
	The well known 16-byte sequence that begins every SQLite database file
        is:
      <pre>
          0x53 0x51 0x4c 0x69 0x74 0x65 0x20 0x66 0x6f 0x72 0x6d 0x61 0x74 0x20 0x33 0x00</pre>

      <p>
        Interpreted as UTF-8 encoded text, this byte sequence corresponds 
        to the string "SQLite format 3" followed by a nul-terminator byte.

      <p>
        The 1, 2 and 4 byte unsigned integers that make up the rest of the
        database file header are described in the following table.

      <table class=striped>
        <tr><th>Byte Range <th>Byte Size <th width=100%>Description
        <tr><td>16..17 <td>2<td>
            Database page size in bytes. See section 
            <cite>pages_and_page_types</cite> for details.

        <tr><td>18     <td>1<td>
            <p style="margin-top:0">
            File-format "write version". Currently, this field
            is always set to 1. If a value greater than 1 is read by SQLite,
            then the library will only open the file for read-only access.

            <p style="margin-bottom:0">
            This field and the next one are intended to be used for 
            forwards compatibility, should the need ever arise. If in the
            future a version of SQLite is created that uses a file format
            that may be safely read but not written by older versions of
            SQLite, then this field will be set to a value greater than 1
            to prevent older SQLite versions from writing to a file that
            uses the new format. 

        <tr><td>19     <td>1<td>
            <p style="margin-top:0">
             File-format "read version". Currently, this 
            field is always set to 1. If a value greater than 1 is read 
            by SQLite, then the library will refuse to open the database 

            <p style="margin-bottom:0">
            Like the "write version" described above, this field exists
            to facilitate some degree of forwards compatibility, in case
            it is ever required. If a version of SQLite created in the 
            future uses a file format that may not be safely read by older
            SQLite versions, then this field will be set to a value greater
            than 1.