Documentation Source Text

Check-in [2d2c9fd38a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the file format documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 2d2c9fd38a782ec4a093262cc150390397d6b88a
User & Date: drh 2010-07-05 15:06:41
Context
2010-07-06
01:27
Adding first draft of WAL file format. check-in: 05824b6e6a user: drh tags: trunk
2010-07-05
15:06
Updates to the file format documentation. check-in: 2d2c9fd38a user: drh tags: trunk
2010-06-29
16:05
Fix a typo in the date/time function documentation. check-in: cf14a52e82 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/docs.in.

   219    219   doc {VDBE Opcodes} {opcode.html} {
   220    220     This document is an automatically generated description of the various
   221    221     opcodes that the VDBE understands.  Programmers can use this document as
   222    222     a reference to better understand the output of EXPLAIN listings from
   223    223     SQLite.
   224    224   }
   225    225   
   226         -doc {SQLite File Format} {fileformat.html} {
          226  +doc {SQLite File Format} {fileformat2.html} {
   227    227     A description of the format used for SQLite database and journal files, and
   228    228     other details required to create software to read and write SQLite 
   229    229     databases without using SQLite.
   230    230   }
   231    231   
   232         -doc {File Format Redux} {fileformat2.html} {
   233         -  An alternative and independent description of the SQLite file format.  
   234         -  This document provides an independent the same information and is 
   235         -  compatible with the previous document, just in a different format.
          232  +doc {SQLite File Format (first edition)} {fileformat.html} {
          233  +  An older and more verbose description of the SQLite file format.  
          234  +  This document provides the same information and is 
          235  +  compatible with the previous document.
   236    236   }
   237    237   
   238    238   doc {Compilation Options} {compile.html} {
   239    239     This document describes the compile time options that may be set to 
   240    240     modify the default behavior of the library or omit optional features
   241    241     in order to reduce binary size.
   242    242   }

Changes to pages/fileformat.in.

     1      1   <title>SQLite Database File Format</title>
     2      2   <tcl>
     3      3   
     4         -hd_keywords {file format}
            4  +hd_keywords {first edition file format document}
     5      5   source [file join $::DOC pages fancyformat.tcl]
     6      6   fancyformat_document "SQLite Database File Format" hlr30000.txt {
     7      7   
     8      8   [h1 "Document Overview"]
     9      9   
    10     10     [h2 "Scope and Purpose"]
    11     11   
................................................................................
    27     27   
    28     28       <li><p> To facilitate the development of external (non-SQLite) software that may 
    29     29               operate directly on SQLite databases stored within a file-system. For
    30     30   	    example a database space analysis utility or a competing database
    31     31   	    client implementation.
    32     32     </ul>
    33     33   
           34  +  <p>
           35  +    A shorter and more recent \[second edition file format document\]
           36  +    also available.  The two file format descriptions are independently
           37  +    written and hence serve as cross-checks of one another.  Any
           38  +    incompatibilities between the two documents should be considered a bug.
           39  +
    34     40     <p>
    35     41       The availability of this information makes an SQLite database an even safer
    36     42       choice for long-term data storage. If at some point in the future the
    37     43       SQLite software library cannot be used to access an SQLite database that
    38     44       contains useful data, a procedure or software module may be developed based
    39     45       on the content of this document to extract the required data.
    40     46   
................................................................................
   630    636               is unlocked, another process may use SQLite to modify the 
   631    637               contents of the file, invalidating the internal cache of the
   632    638               first process. When the file is relocked, the first process can
   633    639               check if the value of the file change counter has been modified
   634    640               since the file was unlocked. If it has not, then the internal
   635    641               cache may be assumed to be valid and may be reused.
   636    642               <td>H33040
          643  +
          644  +        [Tr]<td>28..31 <td>4<td>
          645  +            <p style="margin-top:0">
          646  +            The in-header database size.  This field holds the logical size
          647  +            of the database file in pages.  This field is only valid if it
          648  +            is nonzero and if the file change counter at offset 24 exactly
          649  +            matches the version-valid-for at offset 92.  The in-header database
          650  +            size will only be valid when the database was last written by
          651  +            SQLite version 3.7.0 or later.  If the in-header database size
          652  +            is valid, then it is used as the logical size of the database.
          653  +            If the in-header database size is not valid, then the actual
          654  +            database file size is examined to determine the logical database
          655  +            size.
          656  +            <td>
   637    657   
   638    658           [Tr]<td>32..35 <td>4<td>
   639    659               Page number of first freelist trunk page. 
   640    660               For more details, refer to section <cite>free_page_list</cite>.
   641    661               <td>H31320
   642    662   
   643    663           [Tr]<td>36..39 <td>4<td>
................................................................................
   714    734               so that it contains no free pages (section
   715    735               <cite>free_page_list</cite>) at the end of each database
   716    736               transaction. If incremental vacuum mode is enabled, then the
   717    737               reorganization is not performed until explicitly requested
   718    738               by the user.
   719    739               <td>H30171
   720    740   
          741  +        [Tr]<td>92..95 <td>4<td>
          742  +            The version-valid-for integer.  This is a copy of the
          743  +            file change counter (offset 24) for when the SQLite version number
          744  +            in offset 96 was written.  This integer is also used to determine
          745  +            if the in-header database size (offset 28) is valid.
          746  +            <td>
          747  +
          748  +        [Tr]<td>99..99 <td>4<td>
          749  +            The SQLite version number (obtained from \[SQLITE_VERSION_NUMBER\])
          750  +            for the instance of SQLite that last wrote to the database file.
          751  +            Only SQLite versions 3.7.0 and later will update this number.
          752  +            <td>
          753  +
   721    754         </table>
   722    755   
   723    756         <p>
   724    757           The four byte block beginning at offset 28 stores a big-endian integer
   725    758           which is the number of pages in the database.  Older versions of
   726    759           SQLite set this integer to zero.  For compatibility, SQLite database
   727    760           readers should be able to deal with either value.
   728    761         </p>
   729    762   
   730    763         <p>
   731         -        The 32 byte block beginning at offset 68 is currently unused.
   732         -        This might change in a future release of SQLite.
          764  +        The 32 byte block beginning at offset 68 is unused in SQLite versions
          765  +        up to and including 3.6.23.1.  The 8 bytes at offset 92 came into use
          766  +        beginning with SQLite version 3.7.0.  The 24 bytes between offset 68
          767  +        and offset 91 might come into use in a future release of SQLite.
   733    768         </p>
   734    769   
   735    770         <p>
   736    771           The following requirements state that certain database header
   737    772           fields must contain defined constant values, even though the sqlite 
   738    773           database file format is designed to allow various values. These fields
   739    774           were intended to be flexible when the SQLite database image format

Changes to pages/fileformat2.in.

     1      1   <title>File Format For SQLite Databases</title>
     2         -<tcl>hd_keywords {file format redux}</tcl>
            2  +<tcl>hd_keywords {file format} {second edition file format document}</tcl>
     3      3   
     4      4   <h1 align=center>
     5      5   The SQLite Database File Format
     6      6   </h1>
     7      7   
     8      8   <p>This document describes and defines the on-disk database file
     9      9   format used by SQLite.</p>
    10     10   
    11     11   <p>This is the second document to define the SQLite database file format.
    12         -The [file format| first document] differs from this one in that it is
           12  +The [first edition file format document] differs from this one in that it is
    13     13   written in a formal style whereas this document attempts to be more
    14     14   conversational.  The two documents were independently written (they have
    15     15   different authors) and hence serve as cross-checks for one another.
    16     16   Both documents should describe exactly the same file format.  
    17         -Any discrepencies between the two documents should be considered a bug.</p>
           17  +Any incompatibilities between the two documents should be considered a bug.</p>
    18     18   
    19     19   <h2>1.0 The Database File</h2>
    20     20   
    21     21   <p>Most of the time the complete state of an SQLite database 
    22     22   is contained a single file on disk called the "main database file".</p>
    23     23   
    24     24   <p>While performing a transaction, SQLite stores some temporary information