Documentation Source Text

  [h2 "Document and Requirements Organization"]

     [Table]
        [Tr] <th> Requirement ids <th> Contents
        [Tr] <td> H50**** <td> Requirement statements specifying the functionality required of the B-Tree module.
        [Tr] <td> H51**** <td> Requirement statements specifying the API provided by the B-Tree module.
        [Tr] <td> L****** <td> Requirement statements specifying some details of the internal workings of the B-Tree module.
      </table>

  [h2 "Glossary"]

    <table id=glossary>
      [Glossary "B-Tree Database Connection" {
        A B-Tree database connection is a single client connection to an in-memory 

      [Glossary "Page cache" {
      }]
      [Glossary "Persistent database" {
      }]
      [Glossary "Read-through cache" {
      }]
      [Glossary "Shared-cache mode" {
      }]
      [Glossary "SQLite Error Code" {
      }]
      [Glossary "Temporary database" {
      }]
    </table>
   

  [h1 "Module Requirements"]

      following requirements, a "new database image" is defined as one that is
      zero pages in size.

      [fancyformat_import_requirement H50080]
      [fancyformat_import_requirement H50090]

    [h3 "Transaction and Savepoint Functions"]

  <ul>
    <li> Begin transaction.

    <li> Rollback transaction.
    <li> Commit transaction.
    <li> Query for transaction state (no-transaction, readonly, read-write).
    <li> Begin savepoint(s).
    <li> Release savepoint(s).
    <li> Rollback savepoint(s).
  </ul>

    <p>

  <ul>
    <li> CommitPhaseOne()/CommitPhaseTwo().
  </ul>

    [h3 "Reading From the Database Image"]
  <ul>
    <li> Open b-tree cursor.
    <li> Close b-tree cursor.
    <li> Seek cursor (and all of its variants).
    <li> Next/Prev cursor operations.

          <br> * To know how many savepoints are open in BtreeBeginTrans().
          <br> * Many, many times to assert() that the db mutex is held when the b-tree layer is accessed..


    [h2 "Opening and Closing Connections"]

    <p>
      This section describes the API offered by the B-Tree module to other
      SQLite sub-systems to open and close B-Tree database connections.

      [btree_api_defn Btree]

    <p>
      A B-Tree database connection is accessed by other SQLite sub-systems
      using an opaque handle, modelled in C code using the type "Btree*".

      [btree_api_defn sqlite3BtreeOpen] 

      [fancyformat_import_requirement H51001]
      [fancyformat_import_requirement H51002]

      [fancyformat_import_requirement H51003]
      [fancyformat_import_requirement H51004]

    <p>
      The combination of the above two requirements implies that if the
      zFilename argument passed to sqlite3BtreeOpen is other than a NULL
      pointer or a pointer to a nul-terminated string, the type of or
      filename of the database that sqlite3BtreeOpen attempts to open a
      connection to are undefined.

    <p>
      Valid values for the <i>flags</i> argument to the sqlite3BtreeOpen
      function consist of the bitwise OR of zero or more of the following
      symbols.

      [btree_api_defn BTREE_OMIT_JOURNAL BTREE_NO_READLOCK]

      [fancyformat_import_requirement H51005]

    <p>
      When opening a connection to a persistent database, the value of the
      BTREE_OMIT_JOURNAL bit in the flags parameter is ignored by
      sqlite3BtreeOpen.

      [fancyformat_import_requirement H51006]

    <p>
      When opening a connection to a temporary database, the value of the
      BTREE_NO_READLOCK bit in the flags parameter is ignored, as temporary
      databases are never locked for either reading or writing 
      (<span class=todo>reference to some requirement for this statement.</span>).
      Whether or not a new page-cache is created when a connection to a
      persistent database is opened is governed by requirements H50040 and
      H50050.

      [fancyformat_import_requirement H51007]
      [fancyformat_import_requirement H51008]

    <p class=todo>
      Requirements explaining how the db parameter to sqlite3BtreeOpen is used. Must be there for something.

      [btree_api_defn sqlite3BtreeClose]

      [fancyformat_import_requirement H51009]

    <p>
      If a call to sqlite3BtreeClose is made with a value that is not a valid
      b-tree database connection handle passed as the only argument, the
      results are undefined.

      [fancyformat_import_requirement H51010]

    <p>
      See also requirement H50070.


    [h2 "Database Image Configuration"]

      <p class=todo>
	This category doesn't work all that well. These APIs are used for other
        things too (i.e. switching to incremental-vacuum mode).

      [btree_api_defn sqlite3BtreeBeginStmt sqlite3BtreeSavepoint]

      [btree_api_defn sqlite3BtreeIsInTrans sqlite3BtreeIsInReadTrans sqlite3BtreeIsInBackup]

    [h2 "What do these do?"]

    <p class=todo>
      The following is used only from within VdbeExec() to check whether or not
      a cursor was opened on a table or index b-tree. Corruption tests can move into
      the b-tree layer.

      [btree_api_defn sqlite3BtreeFlags]

      <p class=todo>
        Where do the following go?

      [btree_api_defn sqlite3BtreeIntegrityCheck sqlite3BtreePager sqlite3BtreeCopyFile]

      [btree_api_defn sqlite3BtreeSchema sqlite3BtreeSchemaLocked sqlite3BtreeLockTable sqlite3BtreeTripAllCursors]

      <p class=todo>
        I know what the following do, but is this mechanism ever used? Or has it been superceded by other tricks in OP_NewRowid?

      [btree_api_defn sqlite3BtreeSetCachedRowid sqlite3BtreeGetCachedRowid]

      <p class=todo>
        Should move to btreeInt.h

      [btree_api_defn BtShared]

    [h2 "APIs not branded sqlite3BtreeXXX()"]

<ul>
<li> sqlite3PagerLockingMode
<li> sqlite3PagerJournalMode
<li> sqlite3PagerIsMemdb (vacuum and backup).
<li> sqlite3PagerJournalSizeLimit
<li> sqlite3PagerFile (used by sqlite3_file_control() and pragma lock_proxy_file).
<li> sqlite3PagerPagecounT (pragma page_count and backup).
<li> Page APIs used by backup routines:
  <ul>
    <li> sqlite3PagerGet
    <li> sqlite3PagerWrite
    <li> sqlite3PagerGetData
    <li> sqlite3PagerGetExtra
    <li> sqlite3PagerUnref
    <li> sqlite3PagerTruncateImage
    <li> sqlite3PagerSync
    <li> sqlite3PagerFile
    <li> sqlite3PagerCommitPhaseOne, sqlite3PagerCommitPhaseTwo
    <li> sqlite3PagerBackupPtr
  </ul>
</ul>


  [h1 "Module Implementation"]

  [h2 "Database Image Traversal and Manipulation"]

     <p class=todo>

HLR H50040
If SQLite is configured to run in shared-cache mode, and a connection is opened
to a persistent database file for which there exists already a page-cache within 
the current processes address space, then the connection opened shall be a
connection to the existing page-cache.

HLR H50050
If a new B-Tree database connection is opened and requirement H50040 does not apply,
then a new page-cache shall be created within the processes address space. The
opened connection shall be a connection to the new page-cache.

HLR H50060
The B-Tree module shall provide an interface to close a B-Tree database connection. 

HLR H50070
If a B-Tree database connection is closed and this causes the associated
page-cache to have zero connections to it, then the page-cache shall be closed
and all associated resources released.

HLR H50080
The B-Tree module shall provide an interface to configure the page-size of a
new database image. 

HLR H50090
The B-Tree module shall provide an interface to configure whether or not a new
database image is auto-vacuum capable.




HLR H51001
If successful, a call to the sqlite3BtreeOpen function shall return SQLITE_OK
and set the value of *ppBtree to contain a new B-Tree database connection
handle.

HLR H51002
If unsuccessful, a call to the sqlite3BtreeOpen function shall return an SQLite
error code other than SQLITE_OK indicating the reason for the failure. The
value of *ppBtree shall not be modified in this case.

HLR H51003
If the zFilename parameter to a call to sqlite3BtreeOpen is NULL or a pointer
to a buffer of which the first byte is a nul (0x00), then sqlite3BtreeOpen
shall attempt to open a connection to a temporary database.

HLR H51004
If the zFilename parameter to a call to sqlite3BtreeOpen is a pointer to a
buffer containing a nul-terminated UTF-8 encoded string, sqlite3BtreeOpen shall
attempt to open a connection to a persistent database.

HLR H51005
If the BTREE_OMIT_JOURNAL bit is set in the flags parameter passed to a 
successful call to sqlite3BtreeOpen to open a temporary database, then the
page-cache created as a result shall not open or use a journal file for any
purpose.

HLR H51006
If the BTREE_NO_READLOCK bit is set in the flags parameter passed to a 
successful call to sqlite3BtreeOpen to open a persistent database and a
new page-cache is created as a result of the call, then the new page-cache 
shall only lock the database file-system representation when writing to
it.

HLR H51007
If the sqlite3BtreeOpen function is called to open a connection to a persistent
database, and the call causes a new page-cache to be created, when opening the
database file using the VFS interface xOpen method the 4th parameter passed to
xOpen (flags) shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen.

HLR H51008
If the sqlite3BtreeOpen function is called to open a connection to a temporary
database, if and when a temporary file is opened to use as secondary storage
using the VFS interface xOpen method the 4th parameter passed to xOpen (flags) 
shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen with the 
SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_EXCLUSIVE and 
SQLITE_OPEN_DELETEONCLOSE bits also set.

HLR H51009
A call to the sqlite3BtreeClose function with a valid b-tree database
connection handle passed as the only argument shall invalidate the handle,
close the b-tree database connection and release all associated resources.

HLR H51010
If a call to sqlite3BtreeClose is made to close a b-tree database connection
while there exist open B-Tree cursors that were opened using the specified
b-tree database connection, they shall be closed automatically from within
sqlite3BtreeClose, just as if their handles were passed to
sqlite3BtreeCloseCursor.