Home | History | Annotate | Download | only in doc
      1  *** Throughout this document, a page is deemed to have been synced
      2      automatically as soon as it is written when PRAGMA synchronous=OFF.
      3      Otherwise, the page is not synced until the xSync method of the VFS
      4      is called successfully on the file containing the page.
      5 
      6  *** Definition:  A page of the database file is said to be "overwriteable" if
      7      one or more of the following are true about the page:
      8  
      9      (a)  The original content of the page as it was at the beginning of
     10           the transaction has been written into the rollback journal and
     11           synced.
     12  
     13      (b)  The page was a freelist leaf page at the start of the transaction.
     14  
     15      (c)  The page number is greater than the largest page that existed in
     16           the database file at the start of the transaction.
     17  
     18  (1) A page of the database file is never overwritten unless one of the
     19      following are true:
     20  
     21      (a) The page and all other pages on the same sector are overwriteable.
     22  
     23      (b) The atomic page write optimization is enabled, and the entire
     24          transaction other than the update of the transaction sequence
     25          number consists of a single page change.
     26  
     27  (2) The content of a page written into the rollback journal exactly matches
     28      both the content in the database when the rollback journal was written
     29      and the content in the database at the beginning of the current
     30      transaction.
     31  
     32  (3) Writes to the database file are an integer multiple of the page size
     33      in length and are aligned to a page boundary.
     34  
     35  (4) Reads from the database file are either aligned on a page boundary and
     36      an integer multiple of the page size in length or are taken from the
     37      first 100 bytes of the database file.
     38  
     39  (5) All writes to the database file are synced prior to the rollback journal
     40      being deleted, truncated, or zeroed.
     41  
     42  (6) If a master journal file is used, then all writes to the database file
     43      are synced prior to the master journal being deleted.
     44  
     45  *** Definition: Two databases (or the same database at two points it time)
     46      are said to be "logically equivalent" if they give the same answer to
     47      all queries.  Note in particular the the content of freelist leaf
     48      pages can be changed arbitarily without effecting the logical equivalence
     49      of the database.
     50  
     51  (7) At any time, if any subset, including the empty set and the total set,
     52      of the unsynced changes to a rollback journal are removed and the 
     53      journal is rolled back, the resulting database file will be logical
     54      equivalent to the database file at the beginning of the transaction.
     55  
     56  (8) When a transaction is rolled back, the xTruncate method of the VFS
     57      is called to restore the database file to the same size it was at
     58      the beginning of the transaction.  (In some VFSes, the xTruncate
     59      method is a no-op, but that does not change the fact the SQLite will
     60      invoke it.)
     61  
     62  (9) Whenever the database file is modified, at least one bit in the range
     63      of bytes from 24 through 39 inclusive will be changed prior to releasing
     64      the EXCLUSIVE lock.
     65 
     66 (10) The pattern of bits in bytes 24 through 39 shall not repeat in less
     67      than one billion transactions.
     68 
     69 (11) A database file is well-formed at the beginning and at the conclusion
     70      of every transaction.
     71 
     72 (12) An EXCLUSIVE lock must be held on the database file before making
     73      any changes to the database file.
     74 
     75 (13) A SHARED lock must be held on the database file before reading any
     76      content out of the database file.
     77