Return to pager-invariants.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / doc

Annotation of embedaddon/sqlite3/doc/pager-invariants.txt, revision 1.1.1.1

1.1       misho       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.