Documentation Source Text

#
# Run this TCL script to generate HTML for the goals.html file.
#
set rcsid {$Id: 34to35.tcl,v 1.4 2007/10/01 13:54:11 drh Exp $}
source common.tcl
header {SQLite Changes From Version 3.4.2 To 3.5.0}

proc CODE {text} {
  puts "<blockquote><pre>"
  puts $text
  puts "</pre></blockquote>"
}
proc SYNTAX {text} {
  puts "<blockquote><pre>"
  set t2 [string map {& &amp; < &lt; > &gt;} $text]
  regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
  puts "<b>$t3</b>"
  puts "</pre></blockquote>"
}
proc IMAGE {name {caption {}}} {
  puts "<center><img src=\"$name\">"
  if {$caption!=""} {
    puts "<br>$caption"
  }
  puts "</center>"
}
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3
  puts "<p>[subst -novar -noback $t3]</p>\n"
}
proc resolve_link {args} {
  set a2 [split $args |]
  set id [string trim [lindex $a2 0]]
  if {[lindex $a2 1]==""} {
    set display [string trim [lindex $a2 0]]
  } else {
    set display [string trim [lrange $a2 1 end]]
  }
  regsub -all {[^a-zA-Z0-9_]} $id {} id
  return "<a href=\"capi3ref.html#$id\">$display</a>"
}
set level(0) 0
set level(1) 0
proc HEADING {n name {tag {}}} {
  if {$tag!=""} {
    puts "<a name=\"$tag\">"
  }
  global level
  incr level($n)
  for {set i [expr {$n+1}]} {$i<10} {incr i} {
    set level($i) 0
  }
  if {$n==0} {
    set num {}
  } elseif {$n==1} {
    set num $level(1).0
  } else {
    set num $level(1)
    for {set i 2} {$i<=$n} {incr i} {
      append num .$level($i)
    }
  }
  incr n 1
  puts "<h$n>$num $name</h$n>"
}

HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0}

PARAGRAPH {
  SQLite version 3.5.0 introduces a new OS interface layer that
  is incompatible with all prior versions of SQLite.  In addition,
  a few existing interfaces have been generalized to work across all
  database connections within a process rather than just all
  connections within a thread.  The purpose of this article
  is to describe the changes to 3.5.0 in detail so that users
  of prior versions of SQLite can judge what, if any, effort will
  be required to upgrade to newer versions.
}

HEADING 1 {Overview Of Changes}

PARAGRAPH {
  A quick enumeration of the changes in SQLite version 3.5.0
  is provide here.  Subsequent sections will describe these
  changes in more detail.
}
PARAGRAPH {
  <ol>
  <li>The OS interface layer has been completely reworked:
  <ol type="a">
  <li>The undocumented <b>sqlite3_os_switch()</b> interface has
      been removed.</li>
  <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
      I/O procedures are now always redefinable.</li>
  <li>Three new objects are defined for specifying I/O procedures:
      [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
  <li>Three new interfaces are used to create alternative OS interfaces:
      [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
      [sqlite3_vfs_find()].</li>
  <li>A new interface has been added to provided additional control over
      the creation of new database connections: [sqlite3_open_v2()].
      The legacy interfaces of [sqlite3_open()] and
      [sqlite3_open16()] continue to be fully supported.</li>
  </ol></li>
  <li>The optional shared cache and memory management features that
      were introduced in version 3.3.0 can now be used across multiple
      threads within the same process.  Formerly, these extensions only
      applied to database connections operating within a single thread.
   <ol type="a">
   <li>The [sqlite3_enable_shared_cache()] interface now applies to all
       threads within a process, not to just the one thread in which it
       was run.</li>
   <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads
       within a process, not to just the one thread in which it was run.</li>
   <li>The [sqlite3_release_memory()] interface will now attempt to reduce
       the memory usages across all database connections in all threads, not
       just connections in the thread where the interface is called.</li>
   <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li>
   </ol></li>
  <li>Restrictions on the use of the same database connection by multiple
      threads have been dropped.  It is now safe for
      multiple threads to use the same database connection at the same
      time.</li>
  <li>There is now a compile-time option that allows an application to
      define alternative malloc()/free() implementations without having
      to modify any core SQLite code.</li>
  <li>There is now a compile-time option that allows an application to
      define alternative mutex implementations without having
      to modify any core SQLite code.</li>
  </ol>
}
PARAGRAPH {
  Of these changes, only 1a and 2a through 2c are incompatibilities
  in any formal sense.
  But users who have previously made custom modifications to the
  SQLite source (for example to add a custom OS layer for embedded
  hardware) might find that these changes have a larger impact.
  On the other hand, an important goal of these changes is to make
  it much easier to customize SQLite for use on different operating
  systems. 
}

HEADING 1 {The OS Interface Layer}

PARAGRAPH {
  If your system defines a custom OS interface for SQLite or if you
  were using the undocumented <b>sqlite3_os_switch()</b>
  interface, then you will need to make modifications in order to
  upgrade to SQLite version 3.5.0.  This may seem painful at first
  glance.  But as you look more closely, you will probably discover
  that your changes are made smaller and easier to understand and manage
  by the new SQLite interface.  It is likely that your changes will
  now also work seamlessly with the SQLite amalgamation.  You will
  no longer need to make any changes to the code SQLite source code.
  All of your changes can be effected by application code and you can
  link against a standard, unmodified version of the SQLite amalgamation.
  Furthermore, the OS interface layer, which was formerly undocumented,
  is now an officially support interface for SQLite.  So you have
  some assurance that this will be a one-time change and that your
  new backend will continue to work in future versions of SQLite.
}

HEADING 2 {The Virtual File System Object}

PARAGRAPH {
  The new OS interface for SQLite is built around an object named
  [sqlite3_vfs].  The "vfs" standard for "Virtual File System".
  The sqlite3_vfs object is basically a structure containing pointers
  to functions that implement the primitive disk I/O operations that
  SQLite needs to perform in order to read and write databases.  
  In this article, we will often refer a sqlite3_vfs objects as a "VFS".
}

PARAGRAPH {
  SQLite is able to use multiple VFSes at the same time.  Each
  individual database connection is associated with just one VFS.
  But if you have multiple database connections, each connection
  can be associated with a different VFS.
}

PARAGRAPH {
  There is always a default VFS.
  The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always
  use the default VFS.
  The new interface for creating database connections,
  [sqlite3_open_v2()], allows you to specify which VFS you want to
  use by name.
}

HEADING 3 {Registering New VFS Objects}

PARAGRAPH {
  Standard builds of SQLite for unix or windows come with a single
  VFS named "unix" or "win32", as appropriate.  This one VFS is also 
  the default.  So if you are using the legacy open functions, everything
  will continue to operate as it has before.  The change is that an application
  now has the flexibility of adding new VFS modules to implement a
  customized OS layer.  The [sqlite3_vfs_register()] API can be used
  to tell SQLite about one or more application-defined VFS modules:
}

CODE {
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
}

PARAGRAPH {
  Applications can call sqlite3_vfs_register at any time, though of course
  a VFS needs to be registered before it can be used.  The first argument
  is a pointer to a customized VFS object that the application has prepared.
  The second argument is true to make the new VFS the default VFS so that
  it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs.
  If the new VFS is not the default, then you will probably have to use
  the new [sqlite3_open_v2()] API to use it.  Note, however, that if
  a new VFS is the only VFS known to SQLite (if SQLite was compiled without
  its usual default VFS or if the pre-compiled default VFS was removed
  using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the
  default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()].
}

PARAGRAPH {
  Standard builds include the default "unix" or "win32" VFSes.
  But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
  built without a default VFS.  In that case, the application must
  register at least one VFS prior to calling [sqlite3_open()].
  This is the approach that embedded applications should use.
  Rather than modifying the SQLite source to to insert an alternative
  OS layer as was done in prior releases of SQLite, instead compile
  an unmodified SQLite source file (preferably the amalgamation)
  with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()]
  to define the interface to the underlying filesystem prior to
  creating any database connections.
}

HEADING 3 {Additional Control Over VFS Objects}

PARAGRAPH {
  The [sqlite3_vfs_unregister()] API is used to remove an existing
  VFS from the system.
}

CODE {
int sqlite3_vfs_unregister(sqlite3_vfs*);
}

PARAGRAPH {
  The [sqlite3_vfs_find()] API is used to locate a particular VFS
  by name.  Its prototype is as follows:
}

CODE {
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
}

PARAGRAPH {
  The argument is the symbolic name for the desired VFS.  If the
  argument is a NULL pointer, then the default VFS is returned.
  The function returns a pointer to the [sqlite3_vfs] object that
  implements the VFS.  Or it returns a NULL pointer if no object
  could be found that matched the search criteria.
}

HEADING 3 {Modifications Of Existing VFSes}

PARAGRAPH {
  Once a VFS has been registered, it should never be modified.  If
  a change in behavior is required, a new VFS should be registered.
  The application could, perhaps, use [sqlite3_vfs_find()] to locate
  the old VFS, make a copy of the old VFS into a new [sqlite3_vfs]
  object, make the desired modifications to the new VFS, unregister
  the old VFS, the register the new VFS in its place.  Existing
  database connections would continue to use the old VFS even after
  it is unregistered, but new database connections would use the
  new VFS.
}  

HEADING 3 {The VFS Object}

PARAGRAPH {
  A VFS object is an instance of the following structure:
}

CODE {
typedef struct sqlite3_vfs sqlite3_vfs;
struct sqlite3_vfs {
  int iVersion;            /* Structure version number */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
  int (*xGetTempName)(sqlite3_vfs*, char *zOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};
}

PARAGRAPH {
  To create a new VFS, an application fills in an instance of this
  structure with appropriate values and then calls [sqlite3_vfs_register()].
}

PARAGRAPH {
  The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0.
  This number may increase in future versions of SQLite if we have to
  modify the VFS object in some way.  We hope that this never happens,
  but the provision is made in case it does.
}

PARAGRAPH {
  The szOsFile field is the size in bytes of the structure that defines
  an open file: the [sqlite3_file] object.  This object will be described
  more fully below.  The point here is that each VFS implementation can
  define its own [sqlite3_file] object containing whatever information
  the VFS implementation needs to store about an open file.  SQLite needs
  to know how big this object is, however, in order to preallocate enough
  space to hold it.
}

PARAGRAPH {
  The mxPathname field is the maximum length of a file pathname that
  this VFS can use.  SQLite sometimes has to preallocate buffers of
  this size, so it should be as small as reasonably possible.  Some
  filesystems permit huge pathnames, but in practice pathnames rarely
  extend beyond 100 bytes or so.  You do not have to put the longest
  pathname that the underlying filesystem can handle here.  You only
  have to put the longest pathname that you want SQLite to be able to
  handle.  A few hundred is a good value in most cases.
}

PARAGRAPH {
  The pNext field is used internally by SQLite.  Specifically, SQLite
  uses this field to form a linked list of registered VFSes.
}

PARAGRAPH {
  The zName field is the symbolic name of the VFS.  This is the name 
  that the [sqlite3_vfs_find()] compares against when it is looking for
  a VFS.
}

PARAGRAPH {
  The pAppData pointer is unused by the SQLite core.  The pointer is
  available to store auxiliary information that a VFS information might
  want to carry around.
}

PARAGRAPH {
  The remaining fields of the [sqlite3_vfs] object all store pointer
  to functions that implement primitive operations.  We call these
  "methods".  The first methods, xOpen, is used to open files on
  the underlying storage media.  The result is an [sqlite3_file]
  object.  There are additional methods, defined by the [sqlite3_file]
  object itself that are used to read and write and close the file.
  The additional methods are detailed below.  The filename is in UTF-8.
  SQLite will guarantee that the zFilename string passed to
  xOpen() is a full pathname as generated by xFullPathname() and
  that the string will be valid and unchanged until xClose() is
  called.  So the [sqlite3_file] can store a pointer to the
   filename if it needs to remember the filename for some reason.
   The flags argument to xOpen() is a copy of the flags argument
   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
   If xOpen() opens a file read-only then it sets *pOutFlags to
   include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be
   set.
   SQLite will also add one of the following flags to the xOpen()
   call, depending on the object being opened:
   <ul>
   <li>  [SQLITE_OPEN_MAIN_DB]
   <li>  [SQLITE_OPEN_MAIN_JOURNAL]
   <li>  [SQLITE_OPEN_TEMP_DB]
   <li>  [SQLITE_OPEN_TEMP_JOURNAL]
   <li>  [SQLITE_OPEN_TRANSIENT_DB]
   <li>  [SQLITE_OPEN_SUBJOURNAL]
   <li>  [SQLITE_OPEN_MASTER_JOURNAL]
   </ul>
   The file I/O implementation can use the object type flags to
   changes the way it deals with files.  For example, an application
   that does not care about crash recovery or rollback, might make
   the open of a journal file a no-op.  Writes to this journal are
   also a no-op.  Any attempt to read the journal returns [SQLITE_IOERR].
   Or the implementation might recognize the a database file will
   be doing page-aligned sector reads and writes in a random order
   and set up its I/O subsystem accordingly.
   SQLite might also add one of the following flags to the xOpen
   method:
   <ul>
   <li> [SQLITE_OPEN_DELETEONCLOSE]
   <li> [SQLITE_OPEN_EXCLUSIVE]
   </ul>
   The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
   deleted when it is closed.  This will always be set for TEMP 
   databases and journals and for subjournals.  The 
   [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
   for exclusive access.  This flag is set for all files except
   for the main database file.
   The [sqlite3_file] structure passed as the third argument to
   xOpen is allocated by the caller.  xOpen just fills it in.  The
   caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
   structure.
}

PARAGRAPH {
  The differences between an [SQLITE_OPEN_TEMP_DB] database and an
  [SQLITE_OPEN_TRANSIENT_DB] database is this:  The [SQLITE_OPEN_TEMP_DB]
  is used for explicitly declared and named TEMP tables (using the
  CREATE TEMP TABLE syntax) or for named tables in a temporary database
  that is created by opening a database with a filename that is an empty
  string.  An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that
  SQLite creates automatically in order to evaluate a subquery or
  ORDER BY or GROUP BY clause.  Both TEMP_DB and TRANSIENT_DB databases
  are private and are deleted automatically.  TEMP_DB databases last
  for the duration of the database connection.  TRANSIENT_DB databases
  last only for the duration of a single SQL statement.
}

PARAGRAPH {
  The xDelete method is used delete a file.  The name of the file is
  given in the second parameter.  The filename will be in UTF-8.
  The VFS must convert the filename into whatever character representation
  the underlying operating system expects.  If the syncDir parameter is
  true, then the xDelete method should not return until the change
  to the directory contents for the directory containing the
  deleted file have been synced to disk in order to insure that the
  file does not "reappear" if a power failure occurs soon after.
}

PARAGRAPH {
  The xAccess method is used to check for access permissions on a file.
  The filename will be UTF-8 encoded.  The flags argument will be
  [SQLITE_ACCESS_EXISTS] to check for the existence of the file,
  [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable
  and writable, or [SQLITE_ACCESS_READ] to check to see if the file is
  at least readable.  The "file" named by the second parameter might
  be a directory or folder name.
}

PARAGRAPH {
  The xGetTempName method computes the name of a temporary file that
  SQLite can use.  The name should be written into the buffer given
  by the second parameter.  SQLite will size that buffer to hold
  at least mxPathname bytes.  The generated filename should be in UTF-8.
  To avoid security problems, the generated temporary filename should
  contain enough randomness to prevent an attacker from guessing the
  temporary filename in advance.
}

PARAGRAPH {
  The xFullPathname method is used to convert a relative pathname
  into a full pathname.  The resulting full pathname is written into
  the buffer provided by the third parameter.  SQLite will size the
  output buffer to at least mxPathname bytes.  Both the input and
  output names should be in UTF-8.
}

PARAGRAPH {
  The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
  accessing shared libraries at run-time.  These methods may be omitted
  (and their pointers set to zero) if the library is compiled with
  SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()]
  interface is never used to enable dynamic extension loading.  The
  xDlOpen method opens a shared library or DLL and returns a pointer to
  a handle.  NULL is returned if the open fails.  If the open fails,
  the xDlError method can be used to obtain a text error message.
  The message is written into the zErrMsg buffer of the third parameter
  which is at least nByte bytes in length.  The xDlSym returns a pointer
  to a symbol in the shared library.  The name of the symbol is given
  by the second parameter.  UTF-8 encoding is assumed.  If the symbol
  is not found a NULL pointer is returned.  The xDlClose routine closes
  the shared library.
}

PARAGRAPH {
  The xRandomness method is used exactly once to initialize the 
  pseudo-random number generator (PRNG) inside of SQLite.  Only
  the xRandomness method on the default VFS is used.  The xRandomness
  methods on other VFSes are never accessed by SQLite.
  The xRandomness routine requests that nByte bytes of randomness
  be written into zOut.  The routine returns the actual number of
  bytes of randomness obtained.  The quality of the randomness so obtained
  will determine the quality of the randomness generated by built-in 
  SQLite functions such as random() and randomblob().  SQLite also
  uses its PRNG to generate temporary file names..  On some platforms
  (ex: windows) SQLite assumes that temporary file names are unique
  without actually testing for collisions, so it is important to have
  good-quality randomness even if the random() and randomblob() 
  functions are never used.
}

PARAGRAPH {
  The xSleep method is used to suspend the calling thread for at
  least the number of microseconds given.  This method is used to
  implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs.
  In the case of [sqlite3_sleep()] the xSleep method of the default
  VFS is always used.  If the underlying system does not have a
  microsecond resolution sleep capability, then the sleep time should
  be rounded up.  xSleep returns this rounded-up value.
}

PARAGRAPH {
  The xCurrentTime method finds the current time and date and writes
  the result as double-precision floating point value into pointer
  provided by the second parameter.  The time and date is in
  coordinated universal time (UTC) and is a fractional julian day number.
}

HEADING 3 {The Open File Object}

PARAGRAPH {
  The result of opening a file is an instance of an [sqlite3_file] object.
  The [sqlite3_file] object is an abstract base class defined as follows:
}

CODE {
typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;
};
}

PARAGRAPH {
  Each VFS implementation will subclass the [sqlite3_file] by adding
  additional fields at the end to hold whatever information the VFS
  needs to know about an open file.  It does not matter what information
  is stored as long as the total size of the structure does not exceed
  the szOsFile value recorded in the [sqlite3_vfs] object.
}

PARAGRAPH {
  The [sqlite3_io_methods] object is a structure that contains pointers
  to methods for reading, writing, and otherwise dealing with files.
  This object is defined as follows:
}

CODE {
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};
}

PARAGRAPH {
  The iVersion field of [sqlite3_io_methods] is provided as insurance
  against future enhancements.  The iVersion value should always be
  1 for SQLite version 3.5.
}

PARAGRAPH {
  The xClose method closes the file.  The space for the [sqlite3_file]
  structure is deallocated by the caller.  But if the [sqlite3_file]
  contains pointers to other allocated memory or resources, those
  allocations should be released by the xClose method.
}

PARAGRAPH {
  The xRead method reads iAmt bytes from the file beginning at a byte
  offset to iOfst.  The data read is stored in the pointer of the
  second parameter.  xRead returns the [SQLITE_OK] on success,
  [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number
  of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for
  any other error.
}

PARAGRAPH {
  The xWrite method writes iAmt bytes of data from the second parameter
  into the file beginning at an offset of iOfst bytes.  If the size of
  the file is less than iOfst bytes prior to the write, then xWrite should
  ensure that the file is extended with zeros up to iOfst bytes prior
  to beginning its write.  xWrite continues to extends the file as
  necessary so that the size of the file is at least iAmt+iOfst bytes 
  at the conclusion of the xWrite call.  The xWrite method returns
  [SQLITE_OK] on success.  If the write cannot complete because the
  underlying storage medium is full, then [SQLITE_FULL] is returned.
  [SQLITE_IOERR_WRITE] should be returned for any other error.
}

PARAGRAPH {
  The xTruncate method truncates a file to be nByte bytes in length.
  If the file is already nByte bytes or less in length then this
  method is a no-op.  The xTruncate method returns [SQLITE_OK] on
  success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong.
}

PARAGRAPH {
  The xSync method is used to force previously written data out of
  operating system cache and into non-volatile memory.  The second
  parameter is usually [SQLITE_SYNC_NORMAL].  If the second parameter
  is [SQLITE_SYNC_FULL] then the xSync method should make sure that
  data has also been flushed through the disk controllers cache.
  The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC
  ioctl() on Mac OS X. The xSync method returns
  [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong.
}

PARAGRAPH {
  The xFileSize() method determines the current size of the file
  in bytes and writes that value into *pSize.  It returns [SQLITE_OK]
  on success and [SQLITE_IOERR_FSTAT] if something goes wrong.
}

PARAGRAPH {
  The xLock and xUnlock methods are used to set and clear file locks.
  SQLite supports five levels of file locks, in order:
  <ul>
  <li> [SQLITE_LOCK_NONE]
  <li> [SQLITE_LOCK_SHARED]
  <li> [SQLITE_LOCK_RESERVED]
  <li> [SQLITE_LOCK_PENDING]
  <li> [SQLITE_LOCK_EXCLUSIVE]
  </ul>
  The underlying implementation can support some subset of these locking
  levels as long as it meets the other requirements of this paragraph.
  The locking level is specified as the second argument to both xLock
  and xUnlock.  The xLock method increases the locking level to the
  specified locking level or higher.  The xUnlock method decreases the
  locking level to no lower than the level specified.  
  [SQLITE_LOCK_NONE] means that the file is unlocked.  [SQLITE_LOCK_SHARED]
  gives permission to read the file.  Multiple database connections can
  hold [SQLITE_LOCK_SHARED] at the same time.
  [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission
  to read the file.  But only a single connection can hold a reserved lock
  at any point in time.  The [SQLITE_LOCK_PENDING] is also permission to
  read the file.  Other connections can continue to read the file as well,
  but no other connection is allowed to escalate a lock from none to shared.
  [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file.  Only a single
  connection can hold an exclusive lock and no other connection can hold
  any lock (other than "none") while one connection is hold an exclusive
  lock.  The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it
  is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else
  goes wrong.  The xUnlock method returns [SQLITE_OK] on success and
  [SQLITE_IOERR_UNLOCK] for problems.
}

PARAGRAPH {
  The xCheckReservedLock method checks to see if another connection or
  another process is currently holding a reserved, pending, or exclusive
  lock on the file.  It returns true or false.
}

PARAGRAPH {
  The xFileControl() method is a generic interface that allows custom
  VFS implementations to directly control an open file using the
  (new and experimental)
  [sqlite3_file_control()] interface.  The second "op" argument
  is an integer opcode.   The third
  argument is a generic pointer which is intended to be a pointer
  to a structure that may contain arguments or space in which to
  write return values.  Potential uses for xFileControl() might be
  functions to enable blocking locks with timeouts, to change the
  locking strategy (for example to use dot-file locks), to inquire
  about the status of a lock, or to break stale locks.  The SQLite
  core reserves opcodes less than 100 for its own use. 
  A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
  Applications that define a custom xFileControl method should use opcodes 
  greater than 100 to avoid conflicts.
}

PARAGRAPH {
  The xSectorSize returns the "sector size" of the underlying
  non-volatile media.  A "sector" is defined as the smallest unit of
  storage that can be written without disturbing adjacent storage.
  On a disk drive the "sector size" has until recently been 512 bytes,
  though there is a push to increase this value to 4KiB.  SQLite needs
  to know the sector size so that it can write a full sector at a
  time, and thus avoid corrupting adjacent storage space if a power
  lose occurs in the middle of a write.
}

PARAGRAPH {
  The xDeviceCharacteristics method returns an integer bit vector that
  defines any special properties that the underlying storage medium might
  have that SQLite can use to increase performance.  The allowed return
  is the bit-wise OR of the following values:
  <ul>
  <li> [SQLITE_IOCAP_ATOMIC]
  <li> [SQLITE_IOCAP_ATOMIC512]
  <li> [SQLITE_IOCAP_ATOMIC1K]
  <li> [SQLITE_IOCAP_ATOMIC2K]
  <li> [SQLITE_IOCAP_ATOMIC4K]
  <li> [SQLITE_IOCAP_ATOMIC8K]
  <li> [SQLITE_IOCAP_ATOMIC16K]
  <li> [SQLITE_IOCAP_ATOMIC32K]
  <li> [SQLITE_IOCAP_ATOMIC64K]
  <li> [SQLITE_IOCAP_SAFE_APPEND]
  <li> [SQLITE_IOCAP_SEQUENTIAL]
  </ul>
  The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are
  atomic in the sense that either the entire write occurs or none of it
  occurs.  The other 
  [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that
  writes of aligned blocks of the indicated size are atomic.
  [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new
  data, the new data is written first and then the file size is updated.
  So if a power failure occurs, there is no chance that the file might have
  been extended with randomness.  The [SQLITE_IOCAP_SEQUENTIAL] bit means
  that all writes occur in the order that they are issued and are not
  reordered by the underlying file system.
}

HEADING 3 {Checklist For Constructing A New VFS}

PARAGRAPH {
  The preceding paragraphs contain a lot of information.
  To ease the task of constructing
  a new VFS for SQLite we offer the following implementation checklist:
}

PARAGRAPH {
  <ol>
  <li> Define an appropriate subclass of the [sqlite3_file] object.
  <li> Implement the methods required by the [sqlite3_io_methods] object.
  <li> Create a static and 
       constant [sqlite3_io_methods] object containing pointers
       to the methods from the previous step.
  <li> Implement the xOpen method that opens a file and populates an
       [sqlite3_file] object, including setting pMethods to
       point to the [sqlite3_io_methods] object from the previous step.
  <li> Implement the other methods required by [sqlite3_vfs].
  <li> Define a static (but not constant) [sqlite3_vfs] structure that
       contains pointers to the xOpen method and the other methods and
       which contains the appropriate values for iVersion, szOsFile,
       mxPathname, zName, and pAppData.
  <li> Implement a procedure that calls [sqlite3_vfs_register()] and
       passes it a pointer to the [sqlite3_vfs] structure from the previous
       step.  This procedure is probably the only exported symbol in the
       source file that implements your VFS.
  </ol>
}

PARAGRAPH {
  Within your application, call the procedure implemented in the last
  step above as part of your initialization process before any
  database connections are opened.  
}

HEADING 1 {The Memory Allocation Subsystem}

PARAGRAPH {
  Beginning with version 3.5, SQLite obtains all of the heap memory it
  needs using the routines [sqlite3_malloc()], [sqlite3_free()], and
  [sqlite3_realloc()].  These routines have existed in prior versions
  of SQLite, but SQLite has previously bypassed these routines and used
  its own memory allocator.  This all changes in version 3.5.0.
}

PARAGRAPH {
  The SQLite source tree actually contains multiple versions of the
  memory allocator.  The default high-speed version found in the
  "mem1.c" source file is used for most builds.  But if the SQLITE_MEMDEBUG
  flag is enabled, a separate memory allocator the "mem2.c" source file
  is used instead.  The mem2.c allocator implements lots of hooks to
  do error checking and to simulate memory allocation failures for testing
  purposes.  Both of these allocators use the malloc()/free() implementation
  in the standard C library.
}

PARAGRAPH {
  Applications are not required to use either of these standard memory
  allocators.  If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
  then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()],
  and [sqlite3_free()] functions is provided.  Instead, the application
  that links against SQLite must provide its own implementation of these
  functions.  The application provided memory allocator is not required
  to use the malloc()/free() implementation in the standard C library.
  An embedded application might provide an alternative memory allocator
  that uses memory for a fixed memory pool set aside for the exclusive
  use of SQLite, for example.
}

PARAGRAPH {
  Applications that implement their own memory allocator must provide
  implementation for the usual three allocation functions 
  [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()].
  And they must also implement a fourth function:
}

CODE {
int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
  void *pArg,
  sqlite3_int64 iThreshold
);
}

PARAGRAPH {
 The [sqlite3_memory_alarm] routine is used to register
 a callback on memory allocation events.
 This routine registers or clears a callbacks that fires when
 the amount of memory allocated exceeds iThreshold.  Only
 a single callback can be registered at a time.  Each call
 to [sqlite3_memory_alarm()] overwrites the previous callback.
 The callback is disabled by setting xCallback to a NULL
 pointer.
}

PARAGRAPH {
 The parameters to the callback are the pArg value, the 
 amount of memory currently in use, and the size of the
 allocation that provoked the callback.  The callback will
 presumably invoke [sqlite3_free()] to free up memory space.
 The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
 but if it does, no additional callbacks will be invoked by
 the recursive calls.
}

PARAGRAPH {
 The [sqlite3_soft_heap_limit()] interface works by registering
 a memory alarm at the soft heap limit and invoking 
 [sqlite3_release_memory()] in the alarm callback.  Application
 programs should not attempt to use the [sqlite3_memory_alarm()]
 interface because doing so will interfere with the
 [sqlite3_soft_heap_limit()] module.  This interface is exposed
 only so that applications can provide their own
 alternative implementation when the SQLite core is
 compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
}

PARAGRAPH {
  The built-in memory allocators in SQLite also provide the following
  additional interfaces:
}

CODE {
sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
}

PARAGRAPH {
  These interfaces can be used by an application to monitor how
  much memory SQLite is using.  The [sqlite3_memory_used()] routine
  returns the number of bytes of memory currently in use and the
  [sqlite3_memory_highwater()] returns the maximum instantaneous
  memory usage.  Neither routine includes the overhead associated
  with the memory allocator.  These routines are provided for use
  by the application.  SQLite never invokes them itself.  So if
  the application is providing its own memory allocation subsystem,
  it can omit these interfaces if desired.
}

HEADING 1 {The Mutex Subsystem}

PARAGRAPH {
  SQLite has always been threadsafe in the sense that it is safe to
  use different SQLite database connections in different threads at the
  same time.  The constraint was that the same database connection
  could not be used in two separate threads at once.  SQLite version 3.5.0
  relaxes this constraint. 
}

PARAGRAPH {
  In order to allow multiple threads to use the same database connection
  at the same time, SQLite must make extensive use of mutexes.  And for
  this reason a new mutex subsystem as been added.  The mutex subsystem
  as the following interface:
}

CODE {
sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);
}

PARAGRAPH {
  Though these routines exist for the use of the SQLite core, 
  application code is free to use these routines as well, if desired.
  A mutex is an [sqlite3_mutex] object.  The [sqlite3_mutex_alloc()]
  routine allocates a new mutex object and returns a pointer to it.
  The argument to [sqlite3_mutex_alloc()] should be 
  [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
  and recursive mutexes, respectively.  If the underlying system does
  not provide non-recursive mutexes, then a recursive mutex can be
  substituted in that case.  The argument to [sqlite3_mutex_alloc()]
  can also be a constant designating one of several static mutexes:
  <ul>
  <li>  [SQLITE_MUTEX_STATIC_MASTER]
  <li>  [SQLITE_MUTEX_STATIC_MEM]
  <li>  [SQLITE_MUTEX_STATIC_MEM2]
  <li>  [SQLITE_MUTEX_STATIC_PRNG]
  <li>  [SQLITE_MUTEX_STATIC_LRU]
  </ul>
  These static mutexes are reserved for use internally by SQLite
  and should not be used by the application.  The static mutexes
  are all non-recursive.
}

PARAGRAPH {
  The [sqlite3_mutex_free()] routine should be used to deallocate
  a non-static mutex.  If a static mutex is passed to this routine
  then the behavior is undefined.
}

PARAGRAPH {
  The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
  if another threads is already there.  [sqlite3_mutex_try()] attempts
  to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another
  thread is already there.  [sqlite3_mutex_leave()] exits a mutex.
  The mutex is held until the number of exits matches the number of
  entrances.  If [sqlite3_mutex_leave()] is called on a mutex that 
  the thread is not currently holding, then the behavior is undefined.
  If any routine is called for a deallocated mutex, then the behavior
  is undefined.
}

PARAGRAPH {
  The SQLite source code provides multiple implementations of these
  APIs, suitable for varying environments.  If SQLite is compiled with
  the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that 
  is fast but does no real mutual exclusion is provided.  That 
  implementation is suitable for use in single-threaded applications
  or applications that only use SQLite in a single thread.  Other
  real mutex implementations are provided based on the underlying
  operating system.
}

PARAGRAPH {
  Embedded applications may wish to provide their own mutex implementation.
  If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
  then the SQLite core provides no mutex subsystem and a mutex subsystem
  that matches the interface described above must be provided by the
  application that links against SQLite.
}

HEADING 1 {Other Interface Changes}

PARAGRAPH {
  Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
  that are technically incompatible.  However, these APIs are seldom
  used and even when they are used it is difficult to imagine a
  scenario where the change might break something.  The changes
  actually makes these interface much more useful and powerful.
}

PARAGRAPH {
  Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API
  would enable and disable the shared cache feature for all connections
  within a single thread - the same thread from which the 
  sqlite3_enable_shared_cache() routine was called.  Database connections
  that used the shared cache were restricted to running in the same
  thread in which they were opened.  Beginning with version 3.5.0,
  the sqlite3_enable_shared_cache() applies to all database connections
  in all threads within the process.  Now database connections running
  in separate threads can share a cache.  And database connections that
  use shared cache can migrate from one thread to another.
}

PARAGRAPH {
  Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper
  bound on heap memory usage for all database connections within a
  single thread.  Each thread could have its own heap limit.  Beginning
  in version 3.5.0, there is a single heap limit for the entire process.
  This seems more restrictive (one limit as opposed to many) but in
  practice it is what most users want.
}

PARAGRAPH {
  Prior to version 3.5.0 the [sqlite3_release_memory()] function would
  try to reclaim memory from all database connections in the same thread
  as the sqlite3_release_memory() call.  Beginning with version 3.5.0,
  the sqlite3_release_memory() function will attempt to reclaim memory
  from all database connections in all threads.
}

HEADING 1 {Summary}

PARAGRAPH {
  The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
  Every source code file in the SQLite core had to be modified, some
  extensively.  And the change introduced some minor incompatibilities
  in the C interface.  But we feel that the benefits of the transition
  from 3.4.2 to 3.5.0 far outweigh the pain of porting.  The new
  VFS layer is now well-defined and stable and should simplify future
  customizations.  The VFS layer, and the separable memory allocator
  and mutex subsystems allow a standard SQLite source code amalgamation
  to be used in an embedded project without change, greatly simplifying
  configuration management.  And the resulting system is much more
  tolerant of highly threaded designs.
}

#FIG 3.2
Portrait
Center
Inches
Letter  
100.00
Single
-2
1200 2
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 8550 3675 9075
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 7200 3675 7725
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 5775 3675 6300
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 3975 3675 4500
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 2625 3675 3150
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 1275 3675 1800
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 9900 3675 10425
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 450 4875 450 4875 1275 2550 1275 2550 450
4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001
4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001
4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001
4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001
4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001
4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001
4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001
4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001
4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001
4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001
4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001
4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001
4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001
4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001
4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001
4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001
4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001
4 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001

#
# Run this Tcl script to generate the sqlite.html file.
#
set rcsid {$Id: arch.tcl,v 1.16 2004/10/10 17:24:54 drh Exp $}
source common.tcl
header {Architecture of SQLite}
puts {
<h2>The Architecture Of SQLite</h2>

<h3>Introduction</h3>

<table align="right" border="1" cellpadding="15" cellspacing="1">
<tr><th>Block Diagram Of SQLite</th></tr>
<tr><td><img src="arch2.gif"></td></tr>
</table>
<p>This document describes the architecture of the SQLite library.
The information here is useful to those who want to understand or
modify the inner workings of SQLite.
</p>

<p>
A block diagram showing the main components of SQLite
and how they interrelate is shown at the right.  The text that
follows will provide a quick overview of each of these components.
</p>


<p>
This document describes SQLite version 3.0.  Version 2.8 and
earlier are similar but the details differ.
</p>

<h3>Interface</h3>

<p>Much of the public interface to the SQLite library is implemented by
functions found in the <b>main.c</b>, <b>legacy.c</b>, and
<b>vdbeapi.c</b> source files
though some routines are
scattered about in other files where they can have access to data 
structures with file scope.  The
<b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>.
<b>sqlite3_mprintf()</b> is found in <b>printf.c</b>.
<b>sqlite3_complete()</b> is in <b>tokenize.c</b>.
The Tcl interface is implemented by <b>tclsqlite.c</b>.  More
information on the C interface to SQLite is
<a href="capi3ref.html">available separately</a>.<p>

<p>To avoid name collisions with other software, all external
symbols in the SQLite library begin with the prefix <b>sqlite3</b>.
Those symbols that are intended for external use (in other words,
those symbols which form the API for SQLite) begin
with <b>sqlite3_</b>.</p>

<h3>Tokenizer</h3>

<p>When a string containing SQL statements is to be executed, the
interface passes that string to the tokenizer.  The job of the tokenizer
is to break the original string up into tokens and pass those tokens
one by one to the parser.  The tokenizer is hand-coded in C in 
the file <b>tokenize.c</b>.

<p>Note that in this design, the tokenizer calls the parser.  People
who are familiar with YACC and BISON may be used to doing things the
other way around -- having the parser call the tokenizer.  The author
of SQLite 
has done it both ways and finds things generally work out nicer for
the tokenizer to call the parser.  YACC has it backwards.</p>

<h3>Parser</h3>

<p>The parser is the piece that assigns meaning to tokens based on
their context.  The parser for SQLite is generated using the
<a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser
generator.  Lemon does the same job as YACC/BISON, but it uses
a different input syntax which is less error-prone.
Lemon also generates a parser which is reentrant and thread-safe.
And lemon defines the concept of a non-terminal destructor so
that it does not leak memory when syntax errors are encountered.
The source file that drives Lemon is found in <b>parse.y</b>.</p>

<p>Because
lemon is a program not normally found on development machines, the
complete source code to lemon (just one C file) is included in the
SQLite distribution in the "tool" subdirectory.  Documentation on
lemon is found in the "doc" subdirectory of the distribution.
</p>

<h3>Code Generator</h3>

<p>After the parser assembles tokens into complete SQL statements,
it calls the code generator to produce virtual machine code that
will do the work that the SQL statements request.  There are many
files in the code generator:
<b>attach.c</b>,
<b>auth.c</b>,
<b>build.c</b>,
<b>delete.c</b>,
<b>expr.c</b>,
<b>insert.c</b>,
<b>pragma.c</b>,
<b>select.c</b>,
<b>trigger.c</b>,
<b>update.c</b>,
<b>vacuum.c</b>
and <b>where.c</b>.
In these files is where most of the serious magic happens.
<b>expr.c</b> handles code generation for expressions.
<b>where.c</b> handles code generation for WHERE clauses on
SELECT, UPDATE and DELETE statements.  The files <b>attach.c</b>,
<b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b>
<b>update.c</b>, and <b>vacuum.c</b> handle the code generation
for SQL statements with the same names.  (Each of these files calls routines
in <b>expr.c</b> and <b>where.c</b> as necessary.)  All other
SQL statements are coded out of <b>build.c</b>.
The <b>auth.c</b> file implements the functionality of
<b>sqlite3_set_authorizer()</b>.</p>

<h3>Virtual Machine</h3>

<p>The program generated by the code generator is executed by
the virtual machine.  Additional information about the virtual
machine is <a href="opcode.html">available separately</a>.
To summarize, the virtual machine implements an abstract computing
engine specifically designed to manipulate database files.  The
machine has a stack which is used for intermediate storage.
Each instruction contains an opcode and
up to three additional operands.</p>

<p>The virtual machine itself is entirely contained in a single
source file <b>vdbe.c</b>.  The virtual machine also has
its own header files: <b>vdbe.h</b> that defines an interface
between the virtual machine and the rest of the SQLite library and
<b>vdbeInt.h</b> which defines structure private the virtual machine.
The <b>vdbeaux.c</b> file contains utilities used by the virtual
machine and interface modules used by the rest of the library to
construct VM programs.  The <b>vdbeapi.c</b> file contains external
interfaces to the virtual machine such as the 
<b>sqlite3_bind_...</b> family of functions.  Individual values
(strings, integer, floating point numbers, and BLOBs) are stored
in an internal object named "Mem" which is implemented by
<b>vdbemem.c</b>.</p>

<p>
SQLite implements SQL functions using callbacks to C-language routines.
Even the built-in SQL functions are implemented this way.  Most of
the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>,
<b>substr()</b>, and so forth) can be found in <b>func.c</b>.
Date and time conversion functions are found in <b>date.c</b>.
</p>

<h3>B-Tree</h3>

<p>An SQLite database is maintained on disk using a B-tree implementation
found in the <b>btree.c</b> source file.  A separate B-tree is used for
each table and index in the database.  All B-trees are stored in the
same disk file.  Details of the file format are recorded in a large
comment at the beginning of <b>btree.c</b>.</p>

<p>The interface to the B-tree subsystem is defined by the header file
<b>btree.h</b>.
</p>

<h3>Page Cache</h3>

<p>The B-tree module requests information from the disk in fixed-size
chunks.  The default chunk size is 1024 bytes but can vary between 512
and 65536 bytes.
The page cache is responsible for reading, writing, and
caching these chunks.
The page cache also provides the rollback and atomic commit abstraction
and takes care of locking of the database file.  The
B-tree driver requests particular pages from the page cache and notifies
the page cache when it wants to modify pages or commit or rollback
changes and the page cache handles all the messy details of making sure
the requests are handled quickly, safely, and efficiently.</p>

<p>The code to implement the page cache is contained in the single C
source file <b>pager.c</b>.  The interface to the page cache subsystem
is defined by the header file <b>pager.h</b>.
</p>

<h3>OS Interface</h3>

<p>
In order to provide portability between POSIX and Win32 operating systems,
SQLite uses an abstraction layer to interface with the operating system.
The interface to the OS abstraction layer is defined in
<b>os.h</b>.  Each supported operating system has its own implementation:
<b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth.
Each of these operating-specific implements typically has its own
header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc.
</p>

<h3>Utilities</h3>

<p>
Memory allocation and caseless string comparison routines are located
in <b>util.c</b>.
Symbol tables used by the parser are maintained by hash tables found
in <b>hash.c</b>.  The <b>utf.c</b> source file contains Unicode
conversion subroutines.
SQLite has its own private implementation of <b>printf()</b> (with
some extensions) in <b>printf.c</b> and its own random number generator
in <b>random.c</b>.
</p>

<h3>Test Code</h3>

<p>
If you count regression test scripts,
more than half the total code base of SQLite is devoted to testing.
There are many <b>assert()</b> statements in the main code files.
In additional, the source files <b>test1.c</b> through <b>test5.c</b>
together with <b>md5.c</b> implement extensions used for testing
purposes only.  The <b>os_test.c</b> backend interface is used to
simulate power failures to verify the crash-recovery mechanism in
the pager.
</p>

}
footer $rcsid

#FIG 3.2
Landscape
Center
Inches
Letter  
100.00
Single
-2
1200 2
0 32 #000000
0 33 #868686
0 34 #dfefd7
0 35 #d7efef
0 36 #efdbef
0 37 #efdbd7
0 38 #e7efcf
0 39 #9e9e9e
6 3225 3900 4650 6000
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 4350 3900 4650
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 5100 3900 5475
4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
-6
6 5400 4725 6825 5250
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800
4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001
-6
6 5400 5550 6825 6075
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625
4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001
-6
6 5400 2775 6825 3750
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775
4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001
4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001
-6
6 5400 1950 6825 2475
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025
4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001
-6
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 1500 3900 1800
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 2250 3900 2550
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 3000 3900 3900
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 4575 1950 5400 1350
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 5400 2925 4650 2325
2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
	 2850 750 4875 750 4875 3375 2850 3375 2850 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 1500 6075 1950
2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
	 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675
2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
	 5175 750 7200 750 7200 4050 5175 4050 5175 750
2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
	 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 2475 6075 2775
4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001
4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

#FIG 3.2
Landscape
Center
Inches
Letter  
100.00
Single
-2
1200 2
0 32 #000000
0 33 #868686
0 34 #dfefd7
0 35 #d7efef
0 36 #efdbef
0 37 #efdbd7
0 38 #e7efcf
0 39 #9e9e9e
6 3225 3900 4650 6000
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 4350 3900 4650
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 5100 3900 5475
4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
-6
6 5175 4275 7200 6150
6 5400 4519 6825 5090
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601
4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001
-6
6 5400 5416 6825 5987
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498
4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001
-6
2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
	 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275
4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001
-6
6 5400 2700 6825 3675
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700
4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001
4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001
-6
6 5400 1875 6825 2400
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950
4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001
-6
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 1500 3900 1800
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 2250 3900 2550
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 3000 3900 3900
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 4575 1950 5400 1350
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 5400 2925 4650 2175
2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
	 2850 750 4875 750 4875 3375 2850 3375 2850 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 1500 6075 1800
2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
	 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675
2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
	 5175 750 7200 750 7200 3975 5175 3975 5175 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 2400 6075 2700
4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

#FIG 3.2
Portrait
Center
Inches
Letter  
100.00
Single
-2
1200 2
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 8550 3675 9075
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 7200 3675 7725
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 5775 3675 6300
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 3975 3675 4500
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 2625 3675 3150
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 1275 3675 1800
2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
	1 1 3.00 75.00 135.00
	 3675 9900 3675 10425
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800
2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
	 2550 450 4875 450 4875 1275 2550 1275 2550 450
4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001
4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001
4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001
4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001
4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001
4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001
4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001
4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001
4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001
4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001
4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001
4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001
4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001
4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001
4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001
4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001
4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001
4 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001

#FIG 3.2
Landscape
Center
Inches
Letter  
100.00
Single
-2
1200 2
0 32 #000000
0 33 #868686
0 34 #dfefd7
0 35 #d7efef
0 36 #efdbef
0 37 #efdbd7
0 38 #e7efcf
0 39 #9e9e9e
6 3225 3900 4650 6000
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 4350 3900 4650
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 5100 3900 5475
4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
-6
6 5400 4725 6825 5250
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800
4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001
-6
6 5400 5550 6825 6075
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625
4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001
-6
6 5400 2775 6825 3750
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775
4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001
4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001
-6
6 5400 1950 6825 2475
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025
4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001
-6
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 1500 3900 1800
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 2250 3900 2550
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 3000 3900 3900
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 4575 1950 5400 1350
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 5400 2925 4650 2325
2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
	 2850 750 4875 750 4875 3375 2850 3375 2850 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 1500 6075 1950
2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
	 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675
2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
	 5175 750 7200 750 7200 4050 5175 4050 5175 750
2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
	 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 2475 6075 2775
4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001
4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

#FIG 3.2
Landscape
Center
Inches
Letter  
100.00
Single
-2
1200 2
0 32 #000000
0 33 #868686
0 34 #dfefd7
0 35 #d7efef
0 36 #efdbef
0 37 #efdbd7
0 38 #e7efcf
0 39 #9e9e9e
6 3225 3900 4650 6000
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 4350 3900 4650
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 5100 3900 5475
4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
-6
6 5175 4275 7200 6150
6 5400 4519 6825 5090
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601
4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001
-6
6 5400 5416 6825 5987
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498
4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001
-6
2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
	 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275
4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001
-6
6 5400 2700 6825 3675
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700
4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001
4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001
-6
6 5400 1875 6825 2400
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950
4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001
-6
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 1500 3900 1800
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 2250 3900 2550
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 3900 3000 3900 3900
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 4575 1950 5400 1350
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 5400 2925 4650 2175
2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
	 2850 750 4875 750 4875 3375 2850 3375 2850 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 1500 6075 1800
2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
	 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675
2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
	 5175 750 7200 750 7200 3975 5175 3975 5175 750
2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
	1 1 1.00 60.00 120.00
	 6075 2400 6075 2700
4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

#
# Run this Tcl script to generate the audit.html file.
#
set rcsid {$Id: audit.tcl,v 1.1 2002/07/13 16:52:35 drh Exp $}

puts {<html>
<head>
  <title>SQLite Security Audit Procedure</title>
</head>
<body bgcolor=white>
<h1 align=center>
SQLite Security Audit Procedure
</h1>}
puts "<p align=center>
(This page was last modified on [lrange $rcsid 3 4] UTC)
</p>"

puts {
<p>
A security audit for SQLite consists of two components.  First, there is
a check for common errors that often lead to security problems.  Second,
an attempt is made to construct a proof that SQLite has certain desirable
security properties.
</p>

<h2>Part I: Things to check</h2>

<p>
Scan all source code and check for the following common errors:
</p>

<ol>
<li><p>
Verify that the destination buffer is large enough to hold its result
in every call to the following routines:
<ul>
<li> <b>strcpy()</b> </li>
<li> <b>strncpy()</b> </li>
<li> <b>strcat()</b> </li>
<li> <b>memcpy()</b> </li>
<li> <b>memset()</b> </li>
<li> <b>memmove()</b> </li>
<li> <b>bcopy()</b> </li>
<li> <b>sprintf()</b> </li>
<li> <b>scanf()</b> </li>
</ul>
</p></li>
<li><p>
Verify that pointers returned by subroutines are not NULL before using
the pointers.  In particular, make sure the return values for the following
routines are checked before they are used:
<ul>
<li> <b>malloc()</b> </li>
<li> <b>realloc()</b> </li>
<li> <b>sqliteMalloc()</b> </li>
<li> <b>sqliteRealloc()</b> </li>
<li> <b>sqliteStrDup()</b> </li>
<li> <b>sqliteStrNDup()</b> </li>
<li> <b>sqliteExpr()</b> </li>
<li> <b>sqliteExprFunction()</b> </li>
<li> <b>sqliteExprListAppend()</b> </li>
<li> <b>sqliteResultSetOfSelect()</b> </li>
<li> <b>sqliteIdListAppend()</b> </li>
<li> <b>sqliteSrcListAppend()</b> </li>
<li> <b>sqliteSelectNew()</b> </li>
<li> <b>sqliteTableNameToTable()</b> </li>
<li> <b>sqliteTableTokenToSrcList()</b> </li>
<li> <b>sqliteWhereBegin()</b> </li>
<li> <b>sqliteFindTable()</b> </li>
<li> <b>sqliteFindIndex()</b> </li>
<li> <b>sqliteTableNameFromToken()</b> </li>
<li> <b>sqliteGetVdbe()</b> </li>
<li> <b>sqlite_mprintf()</b> </li>
<li> <b>sqliteExprDup()</b> </li>
<li> <b>sqliteExprListDup()</b> </li>
<li> <b>sqliteSrcListDup()</b> </li>
<li> <b>sqliteIdListDup()</b> </li>
<li> <b>sqliteSelectDup()</b> </li>
<li> <b>sqliteFindFunction()</b> </li>
<li> <b>sqliteTriggerSelectStep()</b> </li>
<li> <b>sqliteTriggerInsertStep()</b> </li>
<li> <b>sqliteTriggerUpdateStep()</b> </li>
<li> <b>sqliteTriggerDeleteStep()</b> </li>
</ul>
</p></li>
<li><p>
On all functions and procedures, verify that pointer parameters are not NULL
before dereferencing those parameters.
</p></li>
<li><p>
Check to make sure that temporary files are opened safely: that the process
will not overwrite an existing file when opening the temp file and that
another process is unable to substitute a file for the temp file being
opened.
</p></li>
</ol>



<h2>Part II: Things to prove</h2>

<p>
Prove that SQLite exhibits the characteristics outlined below:
</p>

<ol>
<li><p>
The following are preconditions:</p>
<p><ul>
<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
<li>An existing SQLite database has been opened.  The return value
    from the call to <b>sqlite_open()</b> is stored in the variable
    <b>db</b>.</li>
<li>The database contains at least one table of the form:
<blockquote><pre>
CREATE TABLE t1(a CLOB);
</pre></blockquote></li>
<li>There are no user-defined functions other than the standard
    build-in functions.</li>
</ul></p>
<p>The following statement of C code is executed:</p>
<blockquote><pre>
sqlite_exec_printf(
   db,
   "INSERT INTO t1(a) VALUES('%q');", 
   0, 0, 0, Z
);
</pre></blockquote>
<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
<ol type="a">
<li><p>
The call to <b>sqlite_exec_printf()</b> will
return in a length of time that is a polynomial in <b>strlen(Z)</b>.
It might return an error code but it will not crash.
</p></li>
<li><p>
At most one new row will be inserted into table t1.
</p></li>
<li><p>
No preexisting rows of t1 will be deleted or modified.
</p></li>
<li><p>
No tables other than t1 will be altered in any way.
</p></li>
<li><p>
No preexisting files on the host computers filesystem, other than
the database file itself, will be deleted or modified.
</p></li>
<li><p>
For some constants <b>K1</b> and <b>K2</b>,
if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b>
will not return SQLITE_NOMEM.
</p></li>
</ol>
</p></li>


<li><p>
The following are preconditions:
<p><ul>
<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
<li>An existing SQLite database has been opened.  The return value
    from the call to <b>sqlite_open()</b> is stored in the variable
    <b>db</b>.</li>
<li>There exists a callback function <b>cb()</b> that appends all
    information passed in through its parameters into a single
    data buffer called <b>Y</b>.</li>
<li>There are no user-defined functions other than the standard
    build-in functions.</li>
</ul></p>
<p>The following statement of C code is executed:</p>
<blockquote><pre>
sqlite_exec(db, Z, cb, 0, 0);
</pre></blockquote>
<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
<ol type="a">
<li><p>
The call to <b>sqlite_exec()</b> will
return in a length of time which is a polynomial in <b>strlen(Z)</b>.
It might return an error code but it will not crash.
</p></li>
<li><p>
After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain
any content from any preexisting file on the host computers file system,
except for the database file.
</p></li>
<li><p>
After the call to <b>sqlite_exec()</b> returns, the database file will
still be well-formed.  It might not contain the same data, but it will
still be a properly constructed SQLite database file.
</p></li>
<li><p>
No preexisting files on the host computers filesystem, other than
the database file itself, will be deleted or modified.
</p></li>
<li><p>
For some constants <b>K1</b> and <b>K2</b>,
if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b>
will not return SQLITE_NOMEM.
</p></li>
</ol>
</p></li>

</ol>
}
puts {
<p><hr /></p>
<p><a href="index.html"><img src="/goback.jpg" border=0 />
Back to the SQLite Home Page</a>
</p>

</body></html>}

#
# Run this Tcl script to generate the autoinc.html file.
#
set rcsid {$Id: }
source common.tcl

if {[llength $argv]>0} {
  set outputdir [lindex $argv 0]
} else {
  set outputdir ""
}

header {SQLite Autoincrement}
puts {
<h1>SQLite Autoincrement</h1>

<p>
In SQLite, every row of every table has an integer ROWID.
The ROWID for each row is unique among all rows in the same table.
In SQLite version 2.8 the ROWID is a 32-bit signed integer.
Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer.
</p>

<p>
You can access the ROWID of an SQLite table using one the special column
names ROWID, _ROWID_, or OID.
Except if you declare an ordinary table column to use one of those special
names, then the use of that name will refer to the declared column not
to the internal ROWID.
</p>

<p>
If a table contains a column of type INTEGER PRIMARY KEY, then that
column becomes an alias for the ROWID.  You can then access the ROWID
using any of four different names, the original three names described above
or the name given to the INTEGER PRIMARY KEY column.  All these names are
aliases for one another and work equally well in any context.
</p>

<p>
When a new row is inserted into an SQLite table, the ROWID can either
be specified as part of the INSERT statement or it can be assigned
automatically by the database engine.  To specify a ROWID manually,
just include it in the list of values to be inserted.  For example:
</p>

<blockquote><pre>
CREATE TABLE test1(a INT, b TEXT);
INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello');
</pre></blockquote>

<p>
If no ROWID is specified on the insert, an appropriate ROWID is created
automatically.  The usual algorithm is to give the newly created row
a ROWID that is one larger than the largest ROWID in the table prior
to the insert.  If the table is initially empty, then a ROWID of 1 is
used.  If the largest ROWID is equal to the largest possible integer
(9223372036854775807 in SQLite version 3.0 and later) then the database
engine starts picking candidate ROWIDs at random until it finds one
that is not previously used.
</p>

<p>
The normal ROWID selection algorithm described above
will generate monotonically increasing
unique ROWIDs as long as you never use the maximum ROWID value and you never
delete the entry in the table with the largest ROWID. 
If you ever delete rows or if you ever create a row with the maximum possible
ROWID, then ROWIDs from previously deleted rows might be reused when creating
new rows and newly created ROWIDs might not be in strictly accending order.
</p>


<h2>The AUTOINCREMENT Keyword</h2>

<p>
If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly
different ROWID selection algorithm is used.  
The ROWID chosen for the new row is one larger than the largest ROWID
that has ever before existed in that same table.  If the table has never
before contained any data, then a ROWID of 1 is used.  If the table
has previously held a row with the largest possible ROWID, then new INSERTs
are not allowed and any attempt to insert a new row will fail with an
SQLITE_FULL error.
</p>

<p>
SQLite keeps track of the largest ROWID that a table has ever held using
the special SQLITE_SEQUENCE table.  The SQLITE_SEQUENCE table is created
and initialized automatically whenever a normal table that contains an
AUTOINCREMENT column is created.  The content of the SQLITE_SEQUENCE table
can be modified using ordinary UPDATE, INSERT, and DELETE statements.
But making modifications to this table will likely perturb the AUTOINCREMENT
key generation algorithm.  Make sure you know what you are doing before
you undertake such changes.
</p>

<p>
The behavior implemented by the AUTOINCREMENT keyword is subtly different
from the default behavior.  With AUTOINCREMENT, rows with automatically
selected ROWIDs are guaranteed to have ROWIDs that have never been used
before by the same table in the same database.  And the automatically generated
ROWIDs are guaranteed to be monotonically increasing.  These are important
properties in certain applications.  But if your application does not
need these properties, you should probably stay with the default behavior
since the use of AUTOINCREMENT requires additional work to be done
as each row is inserted and thus causes INSERTs to run a little slower.
}
footer $rcsid

#
# Run this Tcl script to generate the sqlite.html file.
#
set rcsid {$Id: c_interface.tcl,v 1.43 2004/11/19 11:59:24 danielk1977 Exp $}
source common.tcl
header {The C language interface to the SQLite library}
puts {
<h2>The C language interface to the SQLite library</h2>

<p>The SQLite library is designed to be very easy to use from
a C or C++ program.  This document gives an overview of the C/C++
programming interface.</p>

<h3>1.0 The Core API</h3>

<p>The interface to the SQLite library consists of three core functions,
one opaque data structure, and some constants used as return values.
The core interface is as follows:</p>

<blockquote><pre>
typedef struct sqlite sqlite;
#define SQLITE_OK           0   /* Successful result */

sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);

void sqlite_close(sqlite *db);

int sqlite_exec(
  sqlite *db,
  char *sql,
  int (*xCallback)(void*,int,char**,char**),
  void *pArg,
  char **errmsg
);
</pre></blockquote>

<p>
The above is all you really need to know in order to use SQLite
in your C or C++ programs.  There are other interface functions
available (and described below) but we will begin by describing
the core functions shown above.
</p>

<a name="sqlite_open">
<h4>1.1 Opening a database</h4>

<p>Use the <b>sqlite_open</b> function to open an existing SQLite
database or to create a new SQLite database.  The first argument
is the database name.  The second argument is intended to signal
whether the database is going to be used for reading and writing
or just for reading.  But in the current implementation, the
second argument to <b>sqlite_open</b> is ignored.
The third argument is a pointer to a string pointer.
If the third argument is not NULL and an error occurs
while trying to open the database, then an error message will be
written to memory obtained from malloc() and *errmsg will be made
to point to this error message.  The calling function is responsible
for freeing the memory when it has finished with it.</p>

<p>The name of an SQLite database is the name of a file that will
contain the database.  If the file does not exist, SQLite attempts
to create and initialize it.  If the file is read-only (due to
permission bits or because it is located on read-only media like
a CD-ROM) then SQLite opens the database for reading only.  The
entire SQL database is stored in a single file on the disk.  But
additional temporary files may be created during the execution of
an SQL command in order to store the database rollback journal or
temporary and intermediate results of a query.</p>

<p>The return value of the <b>sqlite_open</b> function is a
pointer to an opaque <b>sqlite</b> structure.  This pointer will
be the first argument to all subsequent SQLite function calls that
deal with the same database.  NULL is returned if the open fails
for any reason.</p>

<a name="sqlite_close">
<h4>1.2 Closing the database</h4>

<p>To close an SQLite database, call the <b>sqlite_close</b>
function passing it the sqlite structure pointer that was obtained
from a prior call to <b>sqlite_open</b>.
If a transaction is active when the database is closed, the transaction
is rolled back.</p>

<a name="sqlite_exec">
<h4>1.3 Executing SQL statements</h4>

<p>The <b>sqlite_exec</b> function is used to process SQL statements
and queries.  This function requires 5 parameters as follows:</p>

<ol>
<li><p>A pointer to the sqlite structure obtained from a prior call
       to <b>sqlite_open</b>.</p></li>
<li><p>A null-terminated string containing the text of one or more
       SQL statements and/or queries to be processed.</p></li>
<li><p>A pointer to a callback function which is invoked once for each
       row in the result of a query.  This argument may be NULL, in which
       case no callbacks will ever be invoked.</p></li>
<li><p>A pointer that is forwarded to become the first argument
       to the callback function.</p></li>
<li><p>A pointer to an error string.  Error messages are written to space
       obtained from malloc() and the error string is made to point to
       the malloced space.  The calling function is responsible for freeing
       this space when it has finished with it.
       This argument may be NULL, in which case error messages are not
       reported back to the calling function.</p></li>
</ol>

<p>
The callback function is used to receive the results of a query.  A
prototype for the callback function is as follows:</p>

<blockquote><pre>
int Callback(void *pArg, int argc, char **argv, char **columnNames){
  return 0;
}
</pre></blockquote>

<a name="callback_row_data">
<p>The first argument to the callback is just a copy of the fourth argument
to <b>sqlite_exec</b>  This parameter can be used to pass arbitrary
information through to the callback function from client code.
The second argument is the number of columns in the query result.
The third argument is an array of pointers to strings where each string
is a single column of the result for that record.  Note that the
callback function reports a NULL value in the database as a NULL pointer,
which is very different from an empty string.  If the i-th parameter
is an empty string, we will get:</p>
<blockquote><pre>
argv[i][0] == 0
</pre></blockquote>
<p>But if the i-th parameter is NULL we will get:</p>
<blockquote><pre>
argv[i] == 0
</pre></blockquote>

<p>The names of the columns are contained in first <i>argc</i>
entries of the fourth argument.
If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
is on (it is off by default) then
the second <i>argc</i> entries in the 4th argument are the datatypes
for the corresponding columns.
</p>

<p>If the <a href="pragma.html#pragma_empty_result_callbacks">
EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of
a query is an empty set, then the callback is invoked once with the
third parameter (argv) set to 0.  In other words
<blockquote><pre>
argv == 0
</pre></blockquote>
The second parameter (argc)
and the fourth parameter (columnNames) are still valid
and can be used to determine the number and names of the result
columns if there had been a result.
The default behavior is not to invoke the callback at all if the
result set is empty.</p>

<a name="callback_returns_nonzero">
<p>The callback function should normally return 0.  If the callback
function returns non-zero, the query is immediately aborted and 
<b>sqlite_exec</b> will return SQLITE_ABORT.</p>

<h4>1.4 Error Codes</h4>

<p>
The <b>sqlite_exec</b> function normally returns SQLITE_OK.  But
if something goes wrong it can return a different value to indicate
the type of error.  Here is a complete list of the return codes:
</p>

<blockquote><pre>
#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
</pre></blockquote>

<p>
The meanings of these various return values are as follows:
</p>

<blockquote>
<dl>
<dt>SQLITE_OK</dt>
<dd><p>This value is returned if everything worked and there were no errors.
</p></dd>
<dt>SQLITE_INTERNAL</dt>
<dd><p>This value indicates that an internal consistency check within
the SQLite library failed.  This can only happen if there is a bug in
the SQLite library.  If you ever get an SQLITE_INTERNAL reply from
an <b>sqlite_exec</b> call, please report the problem on the SQLite
mailing list.
</p></dd>
<dt>SQLITE_ERROR</dt>
<dd><p>This return value indicates that there was an error in the SQL
that was passed into the <b>sqlite_exec</b>.
</p></dd>
<dt>SQLITE_PERM</dt>
<dd><p>This return value says that the access permissions on the database
file are such that the file cannot be opened.
</p></dd>
<dt>SQLITE_ABORT</dt>
<dd><p>This value is returned if the callback function returns non-zero.
</p></dd>
<dt>SQLITE_BUSY</dt>
<dd><p>This return code indicates that another program or thread has
the database locked.  SQLite allows two or more threads to read the
database at the same time, but only one thread can have the database
open for writing at the same time.  Locking in SQLite is on the
entire database.</p>
</p></dd>
<dt>SQLITE_LOCKED</dt>
<dd><p>This return code is similar to SQLITE_BUSY in that it indicates
that the database is locked.  But the source of the lock is a recursive
call to <b>sqlite_exec</b>.  This return can only occur if you attempt
to invoke sqlite_exec from within a callback routine of a query
from a prior invocation of sqlite_exec.  Recursive calls to
sqlite_exec are allowed as long as they do
not attempt to write the same table.
</p></dd>
<dt>SQLITE_NOMEM</dt>
<dd><p>This value is returned if a call to <b>malloc</b> fails.
</p></dd>
<dt>SQLITE_READONLY</dt>
<dd><p>This return code indicates that an attempt was made to write to
a database file that is opened for reading only.
</p></dd>
<dt>SQLITE_INTERRUPT</dt>
<dd><p>This value is returned if a call to <b>sqlite_interrupt</b>
interrupts a database operation in progress.
</p></dd>
<dt>SQLITE_IOERR</dt>
<dd><p>This value is returned if the operating system informs SQLite
that it is unable to perform some disk I/O operation.  This could mean
that there is no more space left on the disk.
</p></dd>
<dt>SQLITE_CORRUPT</dt>
<dd><p>This value is returned if SQLite detects that the database it is
working on has become corrupted.  Corruption might occur due to a rogue
process writing to the database file or it might happen due to an 
perviously undetected logic error in of SQLite. This value is also
returned if a disk I/O error occurs in such a way that SQLite is forced
to leave the database file in a corrupted state.  The latter should only
happen due to a hardware or operating system malfunction.
</p></dd>
<dt>SQLITE_FULL</dt>
<dd><p>This value is returned if an insertion failed because there is
no space left on the disk, or the database is too big to hold any
more information.  The latter case should only occur for databases
that are larger than 2GB in size.
</p></dd>
<dt>SQLITE_CANTOPEN</dt>
<dd><p>This value is returned if the database file could not be opened
for some reason.
</p></dd>
<dt>SQLITE_PROTOCOL</dt>
<dd><p>This value is returned if some other process is messing with
file locks and has violated the file locking protocol that SQLite uses
on its rollback journal files.
</p></dd>
<dt>SQLITE_SCHEMA</dt>
<dd><p>When the database first opened, SQLite reads the database schema
into memory and uses that schema to parse new SQL statements.  If another
process changes the schema, the command currently being processed will
abort because the virtual machine code generated assumed the old
schema.  This is the return code for such cases.  Retrying the
command usually will clear the problem.
</p></dd>
<dt>SQLITE_TOOBIG</dt>
<dd><p>SQLite will not store more than about 1 megabyte of data in a single
row of a single table.  If you attempt to store more than 1 megabyte
in a single row, this is the return code you get.
</p></dd>
<dt>SQLITE_CONSTRAINT</dt>
<dd><p>This constant is returned if the SQL statement would have violated
a database constraint.
</p></dd>
<dt>SQLITE_MISMATCH</dt>
<dd><p>This error occurs when there is an attempt to insert non-integer
data into a column labeled INTEGER PRIMARY KEY.  For most columns, SQLite
ignores the data type and allows any kind of data to be stored.  But
an INTEGER PRIMARY KEY column is only allowed to store integer data.
</p></dd>
<dt>SQLITE_MISUSE</dt>
<dd><p>This error might occur if one or more of the SQLite API routines
is used incorrectly.  Examples of incorrect usage include calling
<b>sqlite_exec</b> after the database has been closed using
<b>sqlite_close</b> or 
calling <b>sqlite_exec</b> with the same
database pointer simultaneously from two separate threads.
</p></dd>
<dt>SQLITE_NOLFS</dt>
<dd><p>This error means that you have attempts to create or access a file
database file that is larger that 2GB on a legacy Unix machine that
lacks large file support.
</p></dd>
<dt>SQLITE_AUTH</dt>
<dd><p>This error indicates that the authorizer callback
has disallowed the SQL you are attempting to execute.
</p></dd>
<dt>SQLITE_ROW</dt>
<dd><p>This is one of the return codes from the
<b>sqlite_step</b> routine which is part of the non-callback API.
It indicates that another row of result data is available.
</p></dd>
<dt>SQLITE_DONE</dt>
<dd><p>This is one of the return codes from the
<b>sqlite_step</b> routine which is part of the non-callback API.
It indicates that the SQL statement has been completely executed and
the <b>sqlite_finalize</b> routine is ready to be called.
</p></dd>
</dl>
</blockquote>

<h3>2.0 Accessing Data Without Using A Callback Function</h3>

<p>
The <b>sqlite_exec</b> routine described above used to be the only
way to retrieve data from an SQLite database.  But many programmers found
it inconvenient to use a callback function to obtain results.  So beginning
with SQLite version 2.7.7, a second access interface is available that
does not use callbacks.
</p>

<p>
The new interface uses three separate functions to replace the single
<b>sqlite_exec</b> function.
</p>

<blockquote><pre>
typedef struct sqlite_vm sqlite_vm;

int sqlite_compile(
  sqlite *db,              /* The open database */
  const char *zSql,        /* SQL statement to be compiled */
  const char **pzTail,     /* OUT: uncompiled tail of zSql */
  sqlite_vm **ppVm,        /* OUT: the virtual machine to execute zSql */
  char **pzErrmsg          /* OUT: Error message. */
);

int sqlite_step(
  sqlite_vm *pVm,          /* The virtual machine to execute */
  int *pN,                 /* OUT: Number of columns in result */
  const char ***pazValue,  /* OUT: Column data */
  const char ***pazColName /* OUT: Column names and datatypes */
);

int sqlite_finalize(
  sqlite_vm *pVm,          /* The virtual machine to be finalized */
  char **pzErrMsg          /* OUT: Error message */
);
</pre></blockquote>

<p>
The strategy is to compile a single SQL statement using
<b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times,
once for each row of output, and finally call <b>sqlite_finalize</b>
to clean up after the SQL has finished execution.
</p>

<h4>2.1 Compiling An SQL Statement Into A Virtual Machine</h4>

<p>
The <b>sqlite_compile</b> "compiles" a single SQL statement (specified
by the second parameter) and generates a virtual machine that is able
to execute that statement.  
As with must interface routines, the first parameter must be a pointer
to an sqlite structure that was obtained from a prior call to
<b>sqlite_open</b>.

<p>
A pointer to the virtual machine is stored in a pointer which is passed
in as the 4th parameter.
Space to hold the virtual machine is dynamically allocated.  To avoid
a memory leak, the calling function must invoke
<b>sqlite_finalize</b> on the virtual machine after it has finished
with it.
The 4th parameter may be set to NULL if an error is encountered during
compilation.
</p>

<p>
If any errors are encountered during compilation, an error message is
written into memory obtained from <b>malloc</b> and the 5th parameter
is made to point to that memory.  If the 5th parameter is NULL, then
no error message is generated.  If the 5th parameter is not NULL, then
the calling function should dispose of the memory containing the error
message by calling <b>sqlite_freemem</b>.
</p>

<p>
If the 2nd parameter actually contains two or more statements of SQL,
only the first statement is compiled.  (This is different from the
behavior of <b>sqlite_exec</b> which executes all SQL statements
in its input string.)  The 3rd parameter to <b>sqlite_compile</b>
is made to point to the first character beyond the end of the first
statement of SQL in the input.  If the 2nd parameter contains only
a single SQL statement, then the 3rd parameter will be made to point
to the '\000' terminator at the end of the 2nd parameter.
</p>

<p>
On success, <b>sqlite_compile</b> returns SQLITE_OK.
Otherwise and error code is returned.
</p>

<h4>2.2 Step-By-Step Execution Of An SQL Statement</h4>

<p>
After a virtual machine has been generated using <b>sqlite_compile</b>
it is executed by one or more calls to <b>sqlite_step</b>.  Each
invocation of <b>sqlite_step</b>, except the last one,
returns a single row of the result.
The number of columns in  the result is stored in the integer that
the 2nd parameter points to.
The pointer specified by the 3rd parameter is made to point
to an array of pointers to column values.
The pointer in the 4th parameter is made to point to an array
of pointers to column names and datatypes.
The 2nd through 4th parameters to <b>sqlite_step</b> convey the
same information as the 2nd through 4th parameters of the
<b>callback</b> routine when using
the <b>sqlite_exec</b> interface.  Except, with <b>sqlite_step</b>
the column datatype information is always included in the in the
4th parameter regardless of whether or not the
<a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
is on or off.
</p>

<p>
Each invocation of <b>sqlite_step</b> returns an integer code that
indicates what happened during that step.  This code may be
SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or
SQLITE_MISUSE.
</p>

<p>
If the virtual machine is unable to open the database file because
it is locked by another thread or process, <b>sqlite_step</b>
will return SQLITE_BUSY.  The calling function should do some other
activity, or sleep, for a short amount of time to give the lock a
chance to clear, then invoke <b>sqlite_step</b> again.  This can
be repeated as many times as desired.
</p>

<p>
Whenever another row of result data is available,
<b>sqlite_step</b> will return SQLITE_ROW.  The row data is
stored in an array of pointers to strings and the 2nd parameter
is made to point to this array.
</p>

<p>
When all processing is complete, <b>sqlite_step</b> will return
either SQLITE_DONE or SQLITE_ERROR.  SQLITE_DONE indicates that the
statement completed successfully and SQLITE_ERROR indicates that there
was a run-time error.  (The details of the error are obtained from
<b>sqlite_finalize</b>.)  It is a misuse of the library to attempt
to call <b>sqlite_step</b> again after it has returned SQLITE_DONE
or SQLITE_ERROR.
</p>

<p>
When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR,
the *pN and *pazColName values are set to the number of columns
in the result set and to the names of the columns, just as they
are for an SQLITE_ROW return.  This allows the calling code to
find the number of result columns and the column names and datatypes
even if the result set is empty.  The *pazValue parameter is always
set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR.
If the SQL being executed is a statement that does not
return a result (such as an INSERT or an UPDATE) then *pN will
be set to zero and *pazColName will be set to NULL.
</p>

<p>
If you abuse the library by trying to call <b>sqlite_step</b>
inappropriately it will attempt return SQLITE_MISUSE.
This can happen if you call sqlite_step() on the same virtual machine
at the same
time from two or more threads or if you call sqlite_step()
again after it returned SQLITE_DONE or SQLITE_ERROR or if you
pass in an invalid virtual machine pointer to sqlite_step().
You should not depend on the SQLITE_MISUSE return code to indicate
an error.  It is possible that a misuse of the interface will go
undetected and result in a program crash.  The SQLITE_MISUSE is
intended as a debugging aid only - to help you detect incorrect
usage prior to a mishap.  The misuse detection logic is not guaranteed
to work in every case.
</p>

<h4>2.3 Deleting A Virtual Machine</h4>

<p>
Every virtual machine that <b>sqlite_compile</b> creates should
eventually be handed to <b>sqlite_finalize</b>.  The sqlite_finalize()
procedure deallocates the memory and other resources that the virtual
machine uses.  Failure to call sqlite_finalize() will result in 
resource leaks in your program.
</p>

<p>
The <b>sqlite_finalize</b> routine also returns the result code
that indicates success or failure of the SQL operation that the
virtual machine carried out.
The value returned by sqlite_finalize() will be the same as would
have been returned had the same SQL been executed by <b>sqlite_exec</b>.
The error message returned will also be the same.
</p>

<p>
It is acceptable to call <b>sqlite_finalize</b> on a virtual machine
before <b>sqlite_step</b> has returned SQLITE_DONE.  Doing so has
the effect of interrupting the operation in progress.  Partially completed
changes will be rolled back and the database will be restored to its
original state (unless an alternative recovery algorithm is selected using
an ON CONFLICT clause in the SQL being executed.)  The effect is the
same as if a callback function of <b>sqlite_exec</b> had returned
non-zero.
</p>

<p>
It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine
that has never been passed to <b>sqlite_step</b> even once.
</p>

<h3>3.0 The Extended API</h3>

<p>Only the three core routines described in section 1.0 are required to use
SQLite.  But there are many other functions that provide 
useful interfaces.  These extended routines are as follows:
</p>

<blockquote><pre>
int sqlite_last_insert_rowid(sqlite*);

int sqlite_changes(sqlite*);

int sqlite_get_table(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg
);

void sqlite_free_table(char**);

void sqlite_interrupt(sqlite*);

int sqlite_complete(const char *sql);

void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*);

void sqlite_busy_timeout(sqlite*, int ms);

const char sqlite_version[];

const char sqlite_encoding[];

int sqlite_exec_printf(
  sqlite*,
  char *sql,
  int (*)(void*,int,char**,char**),
  void*,
  char **errmsg,
  ...
);

int sqlite_exec_vprintf(
  sqlite*,
  char *sql,
  int (*)(void*,int,char**,char**),
  void*,
  char **errmsg,
  va_list
);

int sqlite_get_table_printf(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg,
  ...
);

int sqlite_get_table_vprintf(
  sqlite*,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg,
  va_list
);

char *sqlite_mprintf(const char *zFormat, ...);

char *sqlite_vmprintf(const char *zFormat, va_list);

void sqlite_freemem(char*);

void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);

</pre></blockquote>

<p>All of the above definitions are included in the "sqlite.h"
header file that comes in the source tree.</p>

<h4>3.1 The ROWID of the most recent insert</h4>

<p>Every row of an SQLite table has a unique integer key.  If the
table has a column labeled INTEGER PRIMARY KEY, then that column
serves as the key.  If there is no INTEGER PRIMARY KEY column then
the key is a unique integer.  The key for a row can be accessed in
a SELECT statement or used in a WHERE or ORDER BY clause using any
of the names "ROWID", "OID", or "_ROWID_".</p>

<p>When you do an insert into a table that does not have an INTEGER PRIMARY
KEY column, or if the table does have an INTEGER PRIMARY KEY but the value
for that column is not specified in the VALUES clause of the insert, then
the key is automatically generated.  You can find the value of the key
for the most recent INSERT statement using the
<b>sqlite_last_insert_rowid</b> API function.</p>

<h4>3.2 The number of rows that changed</h4>

<p>The <b>sqlite_changes</b> API function returns the number of rows
that have been inserted, deleted, or modified since the database was
last quiescent.  A "quiescent" database is one in which there are
no outstanding calls to <b>sqlite_exec</b> and no VMs created by
<b>sqlite_compile</b> that have not been finalized by <b>sqlite_finalize</b>.
In common usage, <b>sqlite_changes</b> returns the number
of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b>
call or since the most recent <b>sqlite_compile</b>.  But if you have
nested calls to <b>sqlite_exec</b> (that is, if the callback routine
of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if
you invoke <b>sqlite_compile</b> to create a new VM while there is
still another VM in existance, then
the meaning of the number returned by <b>sqlite_changes</b> is more
complex.
The number reported includes any changes
that were later undone by a ROLLBACK or ABORT.  But rows that are
deleted because of a DROP TABLE are <em>not</em> counted.</p>

<p>SQLite implements the command "<b>DELETE FROM table</b>" (without
a WHERE clause) by dropping the table then recreating it.  
This is much faster than deleting the elements of the table individually.
But it also means that the value returned from <b>sqlite_changes</b>
will be zero regardless of the number of elements that were originally
in the table.  If an accurate count of the number of elements deleted
is necessary, use "<b>DELETE FROM table WHERE 1</b>" instead.</p>

<h4>3.3 Querying into memory obtained from malloc()</h4>

<p>The <b>sqlite_get_table</b> function is a wrapper around
<b>sqlite_exec</b> that collects all the information from successive
callbacks and writes it into memory obtained from malloc().  This
is a convenience function that allows the application to get the
entire result of a database query with a single function call.</p>

<p>The main result from <b>sqlite_get_table</b> is an array of pointers
to strings.  There is one element in this array for each column of
each row in the result.  NULL results are represented by a NULL
pointer. In addition to the regular data, there is an added row at the 
beginning of the array that contains the name of each column of the
result.</p>

<p>As an example, consider the following query:</p>

<blockquote>
SELECT employee_name, login, host FROM users WHERE login LIKE 'd%';
</blockquote>

<p>This query will return the name, login and host computer name
for every employee whose login begins with the letter "d".  If this
query is submitted to <b>sqlite_get_table</b> the result might
look like this:</p>

<blockquote>
nrow = 2<br>
ncolumn = 3<br>
result[0] = "employee_name"<br>
result[1] = "login"<br>
result[2] = "host"<br>
result[3] = "dummy"<br>
result[4] = "No such user"<br>
result[5] = 0<br>
result[6] = "D. Richard Hipp"<br>
result[7] = "drh"<br>
result[8] = "zadok"
</blockquote>

<p>Notice that the "host" value for the "dummy" record is NULL so
the result[] array contains a NULL pointer at that slot.</p>

<p>If the result set of a query is empty, then by default
<b>sqlite_get_table</b> will set nrow to 0 and leave its
result parameter is set to NULL.  But if the EMPTY_RESULT_CALLBACKS
pragma is ON then the result parameter is initialized to the names
of the columns only.  For example, consider this query which has
an empty result set:</p>

<blockquote>
SELECT employee_name, login, host FROM users WHERE employee_name IS NULL;
</blockquote>

<p>
The default behavior gives this results:
</p>

<blockquote>
nrow = 0<br>
ncolumn = 0<br>
result = 0<br>
</blockquote>

<p>
But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following
is returned:
</p>

<blockquote>
nrow = 0<br>
ncolumn = 3<br>
result[0] = "employee_name"<br>
result[1] = "login"<br>
result[2] = "host"<br>
</blockquote>

<p>Memory to hold the information returned by <b>sqlite_get_table</b>
is obtained from malloc().  But the calling function should not try
to free this information directly.  Instead, pass the complete table
to <b>sqlite_free_table</b> when the table is no longer needed.
It is safe to call <b>sqlite_free_table</b> with a NULL pointer such
as would be returned if the result set is empty.</p>

<p>The <b>sqlite_get_table</b> routine returns the same integer
result code as <b>sqlite_exec</b>.</p>

<h4>3.4 Interrupting an SQLite operation</h4>

<p>The <b>sqlite_interrupt</b> function can be called from a
different thread or from a signal handler to cause the current database
operation to exit at its first opportunity.  When this happens,
the <b>sqlite_exec</b> routine (or the equivalent) that started
the database operation will return SQLITE_INTERRUPT.</p>

<h4>3.5 Testing for a complete SQL statement</h4>

<p>The next interface routine to SQLite is a convenience function used
to test whether or not a string forms a complete SQL statement.
If the <b>sqlite_complete</b> function returns true when its input
is a string, then the argument forms a complete SQL statement.
There are no guarantees that the syntax of that statement is correct,
but we at least know the statement is complete.  If <b>sqlite_complete</b>
returns false, then more text is required to complete the SQL statement.</p>

<p>For the purpose of the <b>sqlite_complete</b> function, an SQL
statement is complete if it ends in a semicolon.</p>

<p>The <b>sqlite</b> command-line utility uses the <b>sqlite_complete</b>
function to know when it needs to call <b>sqlite_exec</b>.  After each
line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b>
on all input in its buffer.  If <b>sqlite_complete</b> returns true, 
then <b>sqlite_exec</b> is called and the input buffer is reset.  If
<b>sqlite_complete</b> returns false, then the prompt is changed to
the continuation prompt and another line of text is read and added to
the input buffer.</p>

<h4>3.6 Library version string</h4>

<p>The SQLite library exports the string constant named
<b>sqlite_version</b> which contains the version number of the
library.  The header file contains a macro SQLITE_VERSION
with the same information.  If desired, a program can compare
the SQLITE_VERSION macro against the <b>sqlite_version</b>
string constant to verify that the version number of the
header file and the library match.</p> 

<h4>3.7 Library character encoding</h4>

<p>By default, SQLite assumes that all data uses a fixed-size
8-bit character (iso8859).  But if you give the --enable-utf8 option
to the configure script, then the library assumes UTF-8 variable
sized characters.  This makes a difference for the LIKE and GLOB
operators and the LENGTH() and SUBSTR() functions.  The static
string <b>sqlite_encoding</b> will be set to either "UTF-8" or
"iso8859" to indicate how the library was compiled.  In addition,
the <b>sqlite.h</b> header file will define one of the
macros <b>SQLITE_UTF8</b> or <b>SQLITE_ISO8859</b>, as appropriate.</p>

<p>Note that the character encoding mechanism used by SQLite cannot
be changed at run-time.  This is a compile-time option only.  The
<b>sqlite_encoding</b> character string just tells you how the library
was compiled.</p>

<h4>3.8 Changing the library's response to locked files</h4>

<p>The <b>sqlite_busy_handler</b> procedure can be used to register
a busy callback with an open SQLite database.  The busy callback will
be invoked whenever SQLite tries to access a database that is locked.
The callback will typically do some other useful work, or perhaps sleep,
in order to give the lock a chance to clear.  If the callback returns
non-zero, then SQLite tries again to access the database and the cycle
repeats.  If the callback returns zero, then SQLite aborts the current
operation and returns SQLITE_BUSY.</p>

<p>The arguments to <b>sqlite_busy_handler</b> are the opaque
structure returned from <b>sqlite_open</b>, a pointer to the busy
callback function, and a generic pointer that will be passed as
the first argument to the busy callback.  When SQLite invokes the
busy callback, it sends it three arguments:  the generic pointer
that was passed in as the third argument to <b>sqlite_busy_handler</b>,
the name of the database table or index that the library is trying
to access, and the number of times that the library has attempted to
access the database table or index.</p>

<p>For the common case where we want the busy callback to sleep,
the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>.
The first argument to <b>sqlite_busy_timeout</b> is a pointer to
an open SQLite database and the second argument is a number of milliseconds.
After <b>sqlite_busy_timeout</b> has been executed, the SQLite library
will wait for the lock to clear for at least the number of milliseconds 
specified before it returns SQLITE_BUSY.  Specifying zero milliseconds for
the timeout restores the default behavior.</p>

<h4>3.9 Using the <tt>_printf()</tt> wrapper functions</h4>

<p>The four utility functions</p>

<p>
<ul>
<li><b>sqlite_exec_printf()</b></li>
<li><b>sqlite_exec_vprintf()</b></li>
<li><b>sqlite_get_table_printf()</b></li>
<li><b>sqlite_get_table_vprintf()</b></li>
</ul>
</p>

<p>implement the same query functionality as <b>sqlite_exec</b>
and <b>sqlite_get_table</b>.  But instead of taking a complete
SQL statement as their second argument, the four <b>_printf</b>
routines take a printf-style format string.  The SQL statement to
be executed is generated from this format string and from whatever
additional arguments are attached to the end of the function call.</p>

<p>There are two advantages to using the SQLite printf
functions instead of <b>sprintf</b>.  First of all, with the
SQLite printf routines, there is never a danger of overflowing a
static buffer as there is with <b>sprintf</b>.  The SQLite
printf routines automatically allocate (and later frees)
as much memory as is 
necessary to hold the SQL statements generated.</p>

<p>The second advantage the SQLite printf routines have over
<b>sprintf</b> are two new formatting options specifically designed
to support string literals in SQL.  Within the format string,
the %q formatting option works very much like %s in that it
reads a null-terminated string from the argument list and inserts
it into the result.  But %q translates the inserted string by
making two copies of every single-quote (') character in the
substituted string.  This has the effect of escaping the end-of-string
meaning of single-quote within a string literal. The %Q formatting
option works similar; it translates the single-quotes like %q and
additionally encloses the resulting string in single-quotes.
If the argument for the %Q formatting options is a NULL pointer,
the resulting string is NULL without single quotes.
</p>

<p>Consider an example.  Suppose you are trying to insert a string
value into a database table where the string value was obtained from
user input.  Suppose the string to be inserted is stored in a variable
named zString.  The code to do the insertion might look like this:</p>

<blockquote><pre>
sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES('%s')",
  0, 0, 0, zString);
</pre></blockquote>

<p>If the zString variable holds text like "Hello", then this statement
will work just fine.  But suppose the user enters a string like 
"Hi y'all!".  The SQL statement generated reads as follows:

<blockquote><pre>
INSERT INTO table1 VALUES('Hi y'all')
</pre></blockquote>

<p>This is not valid SQL because of the apostrophy in the word "y'all".
But if the %q formatting option is used instead of %s, like this:</p>

<blockquote><pre>
sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES('%q')",
  0, 0, 0, zString);
</pre></blockquote>

<p>Then the generated SQL will look like the following:</p>

<blockquote><pre>
INSERT INTO table1 VALUES('Hi y''all')
</pre></blockquote>

<p>Here the apostrophy has been escaped and the SQL statement is well-formed.
When generating SQL on-the-fly from data that might contain a
single-quote character ('), it is always a good idea to use the
SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
</p>

<p>If the %Q formatting option is used instead of %q, like this:</p>

<blockquote><pre>
sqlite_exec_printf(db,
  "INSERT INTO table1 VALUES(%Q)",
  0, 0, 0, zString);
</pre></blockquote>

<p>Then the generated SQL will look like the following:</p>

<blockquote><pre>
INSERT INTO table1 VALUES('Hi y''all')
</pre></blockquote>

<p>If the value of the zString variable is NULL, the generated SQL
will look like the following:</p>

<blockquote><pre>
INSERT INTO table1 VALUES(NULL)
</pre></blockquote>

<p>All of the _printf() routines above are built around the following
two functions:</p>

<blockquote><pre>
char *sqlite_mprintf(const char *zFormat, ...);
char *sqlite_vmprintf(const char *zFormat, va_list);
</pre></blockquote>

<p>The <b>sqlite_mprintf()</b> routine works like the the standard library
<b>sprintf()</b> except that it writes its results into memory obtained
from malloc() and returns a pointer to the malloced buffer.  
<b>sqlite_mprintf()</b> also understands the %q and %Q extensions described
above.  The <b>sqlite_vmprintf()</b> is a varargs version of the same
routine.  The string pointer that these routines return should be freed
by passing it to <b>sqlite_freemem()</b>.
</p>

<h4>3.10 Performing background jobs during large queries</h3>

<p>The <b>sqlite_progress_handler()</b> routine can be used to register a
callback routine with an SQLite database to be invoked periodically during long
running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various
wrapper functions.
</p>

<p>The callback is invoked every N virtual machine operations, where N is
supplied as the second argument to <b>sqlite_progress_handler()</b>. The third
and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the
routine to be invoked and a void pointer to be passed as the first argument to
it.
</p>

<p>The time taken to execute each virtual machine operation can vary based on
many factors.  A typical value for a 1 GHz PC is between half and three million
per second but may be much higher or lower, depending on the query.  As such it
is difficult to schedule background operations based on virtual machine
operations. Instead, it is recommended that a callback be scheduled relatively
frequently (say every 1000 instructions) and external timer routines used to
determine whether or not background jobs need to be run.  
</p>

<a name="cfunc">
<h3>4.0 Adding New SQL Functions</h3>

<p>Beginning with version 2.4.0, SQLite allows the SQL language to be
extended with new functions implemented as C code.  The following interface
is used:
</p>

<blockquote><pre>
typedef struct sqlite_func sqlite_func;

int sqlite_create_function(
  sqlite *db,
  const char *zName,
  int nArg,
  void (*xFunc)(sqlite_func*,int,const char**),
  void *pUserData
);
int sqlite_create_aggregate(
  sqlite *db,
  const char *zName,
  int nArg,
  void (*xStep)(sqlite_func*,int,const char**),
  void (*xFinalize)(sqlite_func*),
  void *pUserData
);

char *sqlite_set_result_string(sqlite_func*,const char*,int);
void sqlite_set_result_int(sqlite_func*,int);
void sqlite_set_result_double(sqlite_func*,double);
void sqlite_set_result_error(sqlite_func*,const char*,int);

void *sqlite_user_data(sqlite_func*);
void *sqlite_aggregate_context(sqlite_func*, int nBytes);
int sqlite_aggregate_count(sqlite_func*);
</pre></blockquote>

<p>
The <b>sqlite_create_function()</b> interface is used to create 
regular functions and <b>sqlite_create_aggregate()</b> is used to
create new aggregate functions.  In both cases, the <b>db</b>
parameter is an open SQLite database on which the functions should
be registered, <b>zName</b> is the name of the new function,
<b>nArg</b> is the number of arguments, and <b>pUserData</b> is
a pointer which is passed through unchanged to the C implementation
of the function.  Both routines return 0 on success and non-zero
if there are any errors.
</p>

<p>
The length of a function name may not exceed 255 characters.
Any attempt to create a function whose name exceeds 255 characters
in length will result in an error.
</p>

<p>
For regular functions, the <b>xFunc</b> callback is invoked once
for each function call.  The implementation of xFunc should call
one of the <b>sqlite_set_result_...</b> interfaces to return its
result.  The <b>sqlite_user_data()</b> routine can be used to
retrieve the <b>pUserData</b> pointer that was passed in when the
function was registered.
</p>

<p>
For aggregate functions, the <b>xStep</b> callback is invoked once
for each row in the result and then <b>xFinalize</b> is invoked at the
end to compute a final answer.  The xStep routine can use the
<b>sqlite_aggregate_context()</b> interface to allocate memory that
will be unique to that particular instance of the SQL function.
This memory will be automatically deleted after xFinalize is called.
The <b>sqlite_aggregate_count()</b> routine can be used to find out
how many rows of data were passed to the aggregate.  The xFinalize
callback should invoke one of the <b>sqlite_set_result_...</b>
interfaces to set the final result of the aggregate.
</p>

<p>
SQLite now implements all of its built-in functions using this
interface.  For additional information and examples on how to create
new SQL functions, review the SQLite source code in the file
<b>func.c</b>.
</p>

<h3>5.0 Multi-Threading And SQLite</h3>

<p>
If SQLite is compiled with the THREADSAFE preprocessor macro set to 1,
then it is safe to use SQLite from two or more threads of the same process
at the same time.  But each thread should have its own <b>sqlite*</b>
pointer returned from <b>sqlite_open</b>.  It is never safe for two
or more threads to access the same <b>sqlite*</b> pointer at the same time.
</p>

<p>
In precompiled SQLite libraries available on the website, the Unix
versions are compiled with THREADSAFE turned off but the windows
versions are compiled with THREADSAFE turned on.  If you need something
different that this you will have to recompile.
</p>

<p>
Under Unix, an <b>sqlite*</b> pointer should not be carried across a
<b>fork()</b> system call into the child process.  The child process
should open its own copy of the database after the <b>fork()</b>.
</p>

<h3>6.0 Usage Examples</h3>

<p>For examples of how the SQLite C/C++ interface can be used,
refer to the source code for the <b>sqlite</b> program in the
file <b>src/shell.c</b> of the source tree.
Additional information about sqlite is available at
<a href="sqlite.html">sqlite.html</a>.
See also the sources to the Tcl interface for SQLite in
the source file <b>src/tclsqlite.c</b>.</p>
}
footer $rcsid

set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}

proc AddHyperlinks {txt} {
  regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
      {\1<a href="capi3ref.html#\2">\2</a>\3} t2
  puts $t2
}

AddHyperlinks {
<h2>C/C++ Interface For SQLite Version 3</h2>

<h3>1.0 Overview</h3>

<p>
SQLite version 3.0 is a new version of SQLite, derived from
the SQLite 2.8.13 code base, but with an incompatible file format
and API.
SQLite version 3.0 was created to answer demand for the following features:
</p>

<ul>
<li>Support for UTF-16.</li>
<li>User-definable text collating sequences.</li>
<li>The ability to store BLOBs in indexed columns.</li>
</ul>

<p>
It was necessary to move to version 3.0 to implement these features because
each requires incompatible changes to the database file format.  Other
incompatible changes, such as a cleanup of the API, were introduced at the
same time under the theory that it is best to get your incompatible changes
out of the way all at once.  
</p>

<p>
The API for version 3.0 is similar to the version 2.X API,
but with some important changes.  Most noticeably, the "<tt>sqlite_</tt>"
prefix that occurs on the beginning of all API functions and data
structures are changed to "<tt>sqlite3_</tt>".  
This avoids confusion between the two APIs and allows linking against both
SQLite 2.X and SQLite 3.0 at the same time.
</p>

<p>
There is no agreement on what the C datatype for a UTF-16
string should be.  Therefore, SQLite uses a generic type of void*
to refer to UTF-16 strings.  Client software can cast the void* 
to whatever datatype is appropriate for their system.
</p>

<h3>2.0 C/C++ Interface</h3>

<p>
The API for SQLite 3.0 includes 83 separate functions in addition
to several data structures and #defines.  (A complete
<a href="capi3ref.html">API reference</a> is provided as a separate document.)
Fortunately, the interface is not nearly as complex as its size implies.
Simple programs can still make do with only 3 functions:
<a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>,
<a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>, and
<a href="capi3ref.html#sqlite3_close">sqlite3_close()</a>.
More control over the execution of the database engine is provided
using
<a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>
to compile an SQLite statement into byte code and
<a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a>
to execute that bytecode.
A family of routines with names beginning with 
<a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a>
is used to extract information about the result set of a query.
Many interface functions come in pairs, with both a UTF-8 and
UTF-16 version.  And there is a collection of routines
used to implement user-defined SQL functions and user-defined
text collating sequences.
</p>


<h4>2.1 Opening and closing a database</h4>

<blockquote><pre>
   typedef struct sqlite3 sqlite3;
   int sqlite3_open(const char*, sqlite3**);
   int sqlite3_open16(const void*, sqlite3**);
   int sqlite3_close(sqlite3*);
   const char *sqlite3_errmsg(sqlite3*);
   const void *sqlite3_errmsg16(sqlite3*);
   int sqlite3_errcode(sqlite3*);
</pre></blockquote>

<p>
The sqlite3_open() routine returns an integer error code rather than
a pointer to the sqlite3 structure as the version 2 interface did.
The difference between sqlite3_open()
and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native
byte order) for the name of the database file.  If a new database file
needs to be created, then sqlite3_open16() sets the internal text
representation to UTF-16 whereas sqlite3_open() sets the text
representation to UTF-8.
</p>

<p>
The opening and/or creating of the database file is deferred until the
file is actually needed.  This allows options and parameters, such
as the native text representation and default page size, to be
set using PRAGMA statements.
</p>

<p>
The sqlite3_errcode() routine returns a result code for the most
recent major API call.  sqlite3_errmsg() returns an English-language
text error message for the most recent error.  The error message is
represented in UTF-8 and will be ephemeral - it could disappear on
the next call to any SQLite API function.  sqlite3_errmsg16() works like
sqlite3_errmsg() except that it returns the error message represented
as UTF-16 in host native byte order.
</p>

<p>
The error codes for SQLite version 3 are unchanged from version 2.
They are as follows:
</p>

<blockquote><pre>
#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
</pre></blockquote>

<h4>2.2 Executing SQL statements</h4>

<blockquote><pre>
   typedef int (*sqlite_callback)(void*,int,char**, char**);
   int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
</pre></blockquote>

<p>
The sqlite3_exec function works much as it did in SQLite version 2.
Zero or more SQL statements specified in the second parameter are compiled
and executed.  Query results are returned to a callback routine.
See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional
information.
</p>

<p>
In SQLite version 3, the sqlite3_exec routine is just a wrapper around
calls to the prepared statement interface.
</p>

<blockquote><pre>
   typedef struct sqlite3_stmt sqlite3_stmt;
   int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
   int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
   int sqlite3_finalize(sqlite3_stmt*);
   int sqlite3_reset(sqlite3_stmt*);
</pre></blockquote>

<p>
The sqlite3_prepare interface compiles a single SQL statement into byte code
for later execution.  This interface is now the preferred way of accessing
the database.
</p>

<p>
The SQL statement is a UTF-8 string for sqlite3_prepare().
The sqlite3_prepare16() works the same way except
that it expects a UTF-16 string as SQL input.
Only the first SQL statement in the input string is compiled.
The fourth parameter is filled in with a pointer to the next (uncompiled)
SQLite statement in the input string, if any.
The sqlite3_finalize() routine deallocates a prepared SQL statement.
All prepared statements must be finalized before the database can be
closed.
The sqlite3_reset() routine resets a prepared SQL statement so that it
can be executed again.
</p>

<p>
The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa"
where "nnn" is an integer and "aaa" is an identifier.
Such tokens represent unspecified literal values (or "wildcards")
to be filled in later by the 
<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface.
Each wildcard has an associated number which is its sequence in the
statement or the "nnn" in the case of a "?nnn" form. 
It is allowed for the same wildcard
to occur more than once in the same SQL statement, in which case
all instance of that wildcard will be filled in with the same value.
Unbound wildcards have a value of NULL.
</p>

<blockquote><pre>
   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   int sqlite3_bind_double(sqlite3_stmt*, int, double);
   int sqlite3_bind_int(sqlite3_stmt*, int, int);
   int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
   int sqlite3_bind_null(sqlite3_stmt*, int);
   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
   int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
</pre></blockquote>

<p>
There is an assortment of sqlite3_bind routines used to assign values
to wildcards in a prepared SQL statement.  Unbound wildcards
are interpreted as NULLs.  Bindings are not reset by sqlite3_reset().
But wildcards can be rebound to new values after an sqlite3_reset().
</p>

<p>
After an SQL statement has been prepared (and optionally bound), it
is executed using:
</p>

<blockquote><pre>
   int sqlite3_step(sqlite3_stmt*);
</pre></blockquote>

<p>
The sqlite3_step() routine return SQLITE_ROW if it is returning a single
row of the result set, or SQLITE_DONE if execution has completed, either
normally or due to an error.  It might also return SQLITE_BUSY if it is
unable to open the database file.  If the return value is SQLITE_ROW, then
the following routines can be used to extract information about that row
of the result set:
</p>

<blockquote><pre>
   const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
   int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
   int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
   int sqlite3_column_count(sqlite3_stmt*);
   const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
   const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
   double sqlite3_column_double(sqlite3_stmt*, int iCol);
   int sqlite3_column_int(sqlite3_stmt*, int iCol);
   long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
   const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
   const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
   const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
   const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
   int sqlite3_column_type(sqlite3_stmt*, int iCol);
</pre></blockquote>

<p>
The 
<a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a>
function returns the number of columns in
the results set.  sqlite3_column_count() can be called at any time after
sqlite3_prepare().  
<a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a>
works similarly to
sqlite3_column_count() except that it only works following sqlite3_step().
If the previous call to sqlite3_step() returned SQLITE_DONE or an error code,
then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will
continue to return the number of columns in the result set.
</p>

<p>Returned data is examined using the other sqlite3_column_***() functions, 
all of which take a column number as their second parameter. Columns are
zero-indexed from left to right. Note that this is different to parameters,
which are indexed starting at one.
</p>

<p>
The sqlite3_column_type() function returns the
datatype for the value in the Nth column.  The return value is one
of these:
</p>

<blockquote><pre>
   #define SQLITE_INTEGER  1
   #define SQLITE_FLOAT    2
   #define SQLITE_TEXT     3
   #define SQLITE_BLOB     4
   #define SQLITE_NULL     5
</pre></blockquote>

<p>
The sqlite3_column_decltype() routine returns text which is the
declared type of the column in the CREATE TABLE statement.  For an
expression, the return type is an empty string.  sqlite3_column_name()
returns the name of the Nth column.  sqlite3_column_bytes() returns
the number of bytes in a column that has type BLOB or the number of bytes
in a TEXT string with UTF-8 encoding.  sqlite3_column_bytes16() returns
the same value for BLOBs but for TEXT strings returns the number of bytes
in a UTF-16 encoding.
sqlite3_column_blob() return BLOB data.  
sqlite3_column_text() return TEXT data as UTF-8.
sqlite3_column_text16() return TEXT data as UTF-16.
sqlite3_column_int() return INTEGER data in the host machines native
integer format.
sqlite3_column_int64() returns 64-bit INTEGER data.
Finally, sqlite3_column_double() return floating point data.
</p>

<p>
It is not necessary to retrieve data in the format specify by
sqlite3_column_type().  If a different format is requested, the data
is converted automatically.
</p>

<p>
Data format conversions can invalidate the pointer returned by
prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
sqlite3_column_text16().  Pointers might be invalided in the following
cases:
</p>
<ul>
<li><p>
The initial content is a BLOB and sqlite3_column_text() 
or sqlite3_column_text16()
is called.  A zero-terminator might need to be added to the string.
</p></li>
<li><p>
The initial content is UTF-8 text and sqlite3_column_bytes16() or
sqlite3_column_text16() is called.  The content must be converted to UTF-16.
</p></li>
<li><p>
The initial content is UTF-16 text and sqlite3_column_bytes() or
sqlite3_column_text() is called.  The content must be converted to UTF-8.
</p></li>
</ul>
<p>
Note that conversions between UTF-16be and UTF-16le 
are always done in place and do
not invalidate a prior pointer, though of course the content of the buffer
that the prior pointer points to will have been modified.  Other kinds
of conversion are done in place when it is possible, but sometime it is
not possible and in those cases prior pointers are invalidated.  
</p>

<p>
The safest and easiest to remember policy is this: assume that any
result from
<ul>
<li>sqlite3_column_blob(),</li>
<li>sqlite3_column_text(), or</li>
<li>sqlite3_column_text16()</li>
</ul>
is invalided by subsequent calls to 
<ul>
<li>sqlite3_column_bytes(),</li>
<li>sqlite3_column_bytes16(),</li>
<li>sqlite3_column_text(), or</li>
<li>sqlite3_column_text16().</li>
</ul>
This means that you should always call sqlite3_column_bytes() or
sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
sqlite3_column_text(), or sqlite3_column_text16().
</p>

<h4>2.3 User-defined functions</h4>

<p>
User defined functions can be created using the following routine:
</p>

<blockquote><pre>
   typedef struct sqlite3_value sqlite3_value;
   int sqlite3_create_function(
     sqlite3 *,
     const char *zFunctionName,
     int nArg,
     int eTextRep,
     void*,
     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
     void (*xFinal)(sqlite3_context*)
   );
   int sqlite3_create_function16(
     sqlite3*,
     const void *zFunctionName,
     int nArg,
     int eTextRep,
     void*,
     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
     void (*xFinal)(sqlite3_context*)
   );
   #define SQLITE_UTF8     1
   #define SQLITE_UTF16    2
   #define SQLITE_UTF16BE  3
   #define SQLITE_UTF16LE  4
   #define SQLITE_ANY      5
</pre></blockquote>

<p>
The nArg parameter specifies the number of arguments to the function.
A value of 0 indicates that any number of arguments is allowed.  The
eTextRep parameter specifies what representation text values are expected
to be in for arguments to this function.  The value of this parameter should
be one of the parameters defined above.  SQLite version 3 allows multiple
implementations of the same function using different text representations.
The database engine chooses the function that minimization the number
of text conversions required.
</p>

<p>
Normal functions specify only xFunc and leave xStep and xFinal set to NULL.
Aggregate functions specify xStep and xFinal and leave xFunc set to NULL.
There is no separate sqlite3_create_aggregate() API.
</p>

<p>
The function name is specified in UTF-8.  A separate sqlite3_create_function16()
API works the same as sqlite_create_function()
except that the function name is specified in UTF-16 host byte order.
</p>

<p>
Notice that the parameters to functions are now pointers to sqlite3_value
structures instead of pointers to strings as in SQLite version 2.X.
The following routines are used to extract useful information from these
"values":
</p>

<blockquote><pre>
   const void *sqlite3_value_blob(sqlite3_value*);
   int sqlite3_value_bytes(sqlite3_value*);
   int sqlite3_value_bytes16(sqlite3_value*);
   double sqlite3_value_double(sqlite3_value*);
   int sqlite3_value_int(sqlite3_value*);
   long long int sqlite3_value_int64(sqlite3_value*);
   const unsigned char *sqlite3_value_text(sqlite3_value*);
   const void *sqlite3_value_text16(sqlite3_value*);
   int sqlite3_value_type(sqlite3_value*);
</pre></blockquote>

<p>
Function implementations use the following APIs to acquire context and
to report results:
</p>

<blockquote><pre>
   void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
   void *sqlite3_user_data(sqlite3_context*);
   void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
   void sqlite3_result_double(sqlite3_context*, double);
   void sqlite3_result_error(sqlite3_context*, const char*, int);
   void sqlite3_result_error16(sqlite3_context*, const void*, int);
   void sqlite3_result_int(sqlite3_context*, int);
   void sqlite3_result_int64(sqlite3_context*, long long int);
   void sqlite3_result_null(sqlite3_context*);
   void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
   void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
   void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
   void *sqlite3_get_auxdata(sqlite3_context*, int);
   void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
</pre></blockquote>

<h4>2.4 User-defined collating sequences</h4>

<p>
The following routines are used to implement user-defined
collating sequences:
</p>

<blockquote><pre>
   sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
      int(*xCompare)(void*,int,const void*,int,const void*));
   sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
      int(*xCompare)(void*,int,const void*,int,const void*));
   sqlite3_collation_needed(sqlite3*, void*, 
      void(*)(void*,sqlite3*,int eTextRep,const char*));
   sqlite3_collation_needed16(sqlite3*, void*,
      void(*)(void*,sqlite3*,int eTextRep,const void*));
</pre></blockquote>

<p>
The sqlite3_create_collation() function specifies a collating sequence name
and a comparison function to implement that collating sequence.  The
comparison function is only used for comparing text values.  The eTextRep
parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or
SQLITE_ANY to specify which text representation the comparison function works
with.  Separate comparison functions can exist for the same collating
sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations.
The sqlite3_create_collation16() works like sqlite3_create_collation() except
that the collation name is specified in UTF-16 host byte order instead of
in UTF-8.
</p>

<p>
The sqlite3_collation_needed() routine registers a callback which the
database engine will invoke if it encounters an unknown collating sequence.
The callback can lookup an appropriate comparison function and invoke
sqlite_3_create_collation() as needed.  The fourth parameter to the callback
is the name of the collating sequence in UTF-8.  For sqlite3_collation_need16()
the callback sends the collating sequence name in UTF-16 host byte order.
</p>
}
footer $rcsid

#
# Run this script to generated a changes.html output file
#
source common.tcl
header {SQLite changes}
puts {
<p>
This page provides a high-level summary of changes to SQLite.
For more detail, refer the the checkin logs generated by
CVS at
<a href="http://www.sqlite.org/cvstrac/timeline">
http://www.sqlite.org/cvstrac/timeline</a>.
</p>

<DL>
}


proc chng {date desc} {
  if {[regexp {\(([0-9.]+)\)} $date all vers]} {
    set label [string map {. _} $vers]
    puts "<A NAME=\"version_$label\">"
  }
  puts "<DT><B>$date</B></DT>"
  regsub -all {[Tt]icket #(\d+)} $desc \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
  puts "<DD><P><UL>$desc</UL></P>"
  puts "</DD>"
}

chng {2007 Nov 05 (3.5.2)} {
<li>Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time
option.
<li>Always open files using FILE_FLAG_RANDOM_ACCESS under windows.
<li>The 3rd parameter of the built-in SUBSTR() function is now optional.
<li>Bug fix: do not invoke the authorizer when reparsing the schema after
a schema change.
<li>Added the experimental malloc-free memory allocator in mem3.c.
<li>Virtual machine stores 64-bit integer and floating point constants
in binary instead of text for a performance boost.
<li>Fix a race condition in test_async.c.
<li>Added the ".timer" command to the CLI
}

chng {2007 Oct 04 (3.5.1)} {
<li><i><b>Nota Bene:</b> We are not using terms "alpha" or "beta" on this
    release because the code is stable and because if we use those terms,
    nobody will upgrade.  However, we still reserve the right to make
    incompatible changes to the new VFS interface in future releases.</i></li>

<li>Fix a bug in the handling of SQLITE_FULL errors that could lead
    to database corruption.  Ticket #2686.
<li>The test_async.c drive now does full file locking and works correctly
    when used simultaneously by multiple processes on the same database.
<li>The CLI ignores whitespace (including comments) at the end of lines
<li>Make sure the query optimizer checks dependences on all terms of
    a compound SELECT statement.  Ticket #2640.
<li>Add demonstration code showing how to build a VFS for a raw
    mass storage without a filesystem.
<li>Added an output buffer size parameter to the xGetTempname() method
    of the VFS layer.
<li>Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset
    when a new transaction is started.
}


chng {2007 Sep 04 (3.5.0) alpha} {
<li>Redesign the OS interface layer.  See
    <a href="34to35.html">34to35.html</a> for details.
    <font color="red">*** Potentially incompatible change ***</font>
<li>The <a href="capi3ref.html#sqlite3_release_memory">
    sqlite3_release_memory()</a>,
    <a href="capi3ref.html#sqlite3_soft_heap_limit">
    sqlite3_soft_heap_limit()</a>,
    and <a href="capi3ref.html#sqlite3_enable_shared_cache">
    sqlite3_enable_shared_cache()</a> interfaces now work cross all
    threads in the process, not just the single thread in which they
    are invoked.
    <font color="red">*** Potentially incompatible change ***</font>
<li>Added the 
    <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
    interface.  
<li>Reimplemented the memory allocation subsystem and made it 
    replacable at compile-time.
<li>Created a new mutex subsystem and made it replacable at
    compile-time.
<li>The same database connection may now be used simultaneously by
    separate threads.
}


chng {2007 August 13 (3.4.2)} {
<li>Fix a database corruption bug that might occur if a ROLLBACK command
is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
soft_heap_limit</a> is set. 
<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.

<li>Add the ability to run a full regression test with a small
<a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>.

<li>Fix other minor problems with using small soft heap limits.

<li>Work-around for 
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>.

<li>Improved error detection of misused aggregate functions.

<li>Improvements to the amalgamation generator script so that all symbols
are prefixed with either SQLITE_PRIVATE or SQLITE_API.
}

chng {2007 July 20 (3.4.1)} {
<li>Fix a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to
    <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
    database corruption</a> if two
    processes are connected to the database at the same time and one
    VACUUMs then the other then modifies the database.</li>
<li>The expression "+column" is now considered the same as "column"
    when computing the collating sequence to use on the expression.</li>
<li>In the <a href="tclsqlite.html">TCL language interface</a>,
   "@variable" instead of "$variable" always binds as a blob.</li>
<li>Added <a href="pragma.html#pragma_freelist_count">PRAGMA freelist_count</a>
    for determining the current size of the freelist.</li>
<li>The <a href="pragma.html#pragma_auto_vacuum">
    PRAGMA auto_vacuum=incremental</a> setting is now persistent.</li>
<li>Add FD_CLOEXEC to all open files under unix.</li>
<li>Fix a bug in the <a href="optoverview.html#minmax">
    min()/max() optimization</a> when applied to
    descending indices.</li>
<li>Make sure the TCL language interface works correctly with 64-bit
    integers on 64-bit machines.</li>
<li>Allow the value -9223372036854775808 as an integer literal in SQL
    statements.</li>
<li>Add the capability of "hidden" columns in virtual tables.</li>
<li>Use the macro SQLITE_PRIVATE (defaulting to "static") on all
    internal functions in the amalgamation.</li>
<li>Add pluggable tokenizers and <a href="http://www.icu-project.org/">ICU</a>
    tokenization support to FTS2</li>
<li>Other minor bug fixes and documentation enhancements</li>
}

chng {2007 June 18 (3.4.0)} {
<li>Fix a bug that can lead to database corruption if an SQLITE_BUSY error
    occurs in the middle of an explicit transaction and that transaction
    is later committed.  
    <a href="http://www.sqlite.org/cvstrac/tktview?tn=2409">Ticket #2409.</a>
    See the
    <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
    CorruptionFollowingBusyError</a> wiki page for details.</i>
<li>Fix a bug that can lead to database corruption if autovacuum mode is
    on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement
    which itself follows a cache overflow inside a transaction.  See
    <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>. 
    </li>
<li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and
    quantities of things SQLite can process.  This change might cause
    compatibility problems for
    applications that use SQLite in the extreme, which is why the current
    release is 3.4.0 instead of 3.3.18.</li>
<li>Added support for <a href="capi3ref.html#sqlite3_blob_open">
    Incremental BLOB I/O</a>.</li>
<li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a>
    and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li>
<li>Added support for <a href="pragma.html#pragma_incremental_vacuum">
    Incremental Vacuum</a>.</li>
<li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport
    ARM7 processors with goofy endianness.</li>
<li>Removed all instances of sprintf() and strcpy() from the core library.</li>
<li>Added support for <a href="http://www.icu-project.org/">
    International Components for Unicode (ICU)</a> to the full-text search
    extensions.
</ul><p>
<ul type="circle">
<li>In the windows OS driver, reacquire a SHARED lock if an attempt to
    acquire an EXCLUSIVE lock fails.  Ticket #2354</li>
<li>Fix the REPLACE() function so that it returns NULL if the second argument
    is an empty string.  Ticket #2324.</li>
<li>Document the hazards of type coversions in
    <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a>
    and related APIs.  Fix unnecessary type conversions.  Ticket #2321.</li>
<li>Internationalization of the TRIM() function.  Ticket #2323</li>
<li>Use memmove() instead of memcpy() when moving between memory regions
    that might overlap.  Ticket #2334</li>
<li>Fix an optimizer bug involving subqueries in a compound SELECT that has
    both an ORDER BY and a LIMIT clause.  Ticket #2339.</li>
<li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf()
    </a> interface does not zero-terminate the buffer if the buffer size is
    less than 1.  Ticket #2341</li>
<li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for
    floating-point NaNs.  Ticket #2345</li>
<li>When converting BLOB to TEXT, use the text encoding of the main database.
    Ticket #2349</li>
<li>Keep the full precision of integers (if possible) when casting to
    NUMERIC.  Ticket #2364</li>
<li>Fix a bug in the handling of UTF16 codepoint 0xE000</li>
<li>Consider explicit collate clauses when matching WHERE constraints
    to indices in the query optimizer.  Ticket #2391</li>
<li>Fix the query optimizer to correctly handle constant expressions in 
    the ON clause of a LEFT JOIN.  Ticket #2403</li>
<li>Fix the query optimizer to handle rowid comparisions to NULL
    correctly.  Ticket #2404</li>
<li>Fix many potental segfaults that could be caused by malicious SQL
    statements.</li>
}

chng {2007 April 25 (3.3.17)} {
<li>When the "write_version" value of the database header is larger than
    what the library understands, make the database read-only instead of
    unreadable.</li>
<li>Other minor bug fixes</li>
}

chng {2007 April 18 (3.3.16)} {
<li>Fix a bug that caused VACUUM to fail if NULLs appeared in a
    UNIQUE column.</li>
<li>Reinstate performance improvements that were added in 3.3.14
    but regressed in 3.3.15.</li>
<li>Fix problems with the handling of ORDER BY expressions on
    compound SELECT statements in subqueries.</li>
<li>Fix a potential segfault when destroying locks on WinCE in
    a multi-threaded environment.</li>
<li>Documentation updates.</li>
}

chng {2007 April 9 (3.3.15)} {
<li>Fix a bug introduced in 3.3.14 that caused a rollback of
    CREATE TEMP TABLE to leave the database connection wedged.</li>
<li>Fix a bug that caused an extra NULL row to be returned when
    a descending query was interrupted by a change to the database.</li>
<li>The FOR EACH STATEMENT clause on a trigger now causes a syntax
    error.  It used to be silently ignored.</li>
<li>Fix an obscure and relatively harmless problem that might have caused
    a resource leak following an I/O error.</li>
<li>Many improvements to the test suite.  Test coverage now exceeded 98%</li>
}

chng {2007 April 2 (3.3.14)} {
<li>Fix a <a href="http://www.sqlite.org/cvstrac/tktview?tn=2273">bug</a>
    in 3.3.13 that could cause a segfault when the IN operator
    is used one one term of a two-column index and the right-hand side of
    the IN operator contains a NULL.</li>
<li>Added a new OS interface method for determining the sector size
    of underlying media:  sqlite3OsSectorSize().</li>
<li>A new algorithm for statements of the form
    INSERT INTO <i>table1</i> SELECT * FROM <i>table2</i>
    is faster and reduces fragmentation.  VACUUM uses statements of
    this form and thus runs faster and defragments better.</li>
<li>Performance enhancements through reductions in disk I/O:
<ul>
<li>Do not read the last page of an overflow chain when
    deleting the row - just add that page to the freelist.</li>
<li>Do not store pages being deleted in the 
    rollback journal.</li>
<li>Do not read in the (meaningless) content of
    pages extracted from the freelist.</li>
<li>Do not flush the page cache (and thus avoiding
    a cache refill) unless another process changes the underlying
    database file.</li>
<li>Truncate rather than delete the rollback journal when committing
    a transaction in exclusive access mode, or when committing the TEMP
    database.</li>
</ul></li>
<li>Added support for exclusive access mode using
    <a href="pragma.html#pragma_locking_mode">
    "PRAGMA locking_mode=EXCLUSIVE"</a></li>
<li>Use heap space instead of stack space for large buffers in the
    pager - useful on embedded platforms with  stack-space
    limitations.</li>
<li>Add a makefile target "sqlite3.c" that builds an amalgamation containing
    the core SQLite library C code in a single file.</li>
<li>Get the library working correctly when compiled 
    with GCC option "-fstrict-aliasing".</li>
<li>Removed the vestigal SQLITE_PROTOCOL error.</li>
<li>Improvements to test coverage, other minor bugs fixed,
    memory leaks plugged,
    code refactored and/or recommented in places for easier reading.</li>
}

chng {2007 February 13 (3.3.13)} {
<li>Add a "fragmentation" measurement in the output of sqlite3_analyzer.</li>
<li>Add the COLLATE operator used to explicitly set the collating sequence
used by an expression.  This feature is considered experimental pending
additional testing.</li>
<li>Allow up to 64 tables in a join - the old limit was 32.</li>
<li>Added two new experimental functions:
<a href="lang_expr.html#randomblobFunc">randomBlob()</a> and
<a href="lang_expr.html#hexFunc">hex()</a>.
Their intended use is to facilitate generating 
<a href="http://en.wikipedia.org/wiki/UUID">UUIDs</a>.
</li>
<li>Fix a problem where
<a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a> was
causing incorrect results for updates on tables with triggers</li>
<li>Fix a bug in the ORDER BY clause optimizer for joins where the
left-most table in the join is constrained by a UNIQUE index.</li>
<li>Fixed a bug in the "copy" method of the TCL interface.</li>
<li>Bug fixes in fts1 and fts2 modules.</li>
}

chng {2007 January 27 (3.3.12)} {
<li>Fix another bug in the IS NULL optimization that was added in
version 3.3.9.</li>
<li>Fix a assertion fault that occurred on deeply nested views.</li>
<li>Limit the amount of output that
<a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a>
generates.</li>
<li>Minor syntactic changes to support a wider variety of compilers.</li>
}

chng {2007 January 22 (3.3.11)} {
<li>Fix another bug in the implementation of the new 
<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.
We'll get it right eventually...</li>
<li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 -
the bug was causing incorrect results on certain LEFT JOINs that included
in the WHERE clause an IS NULL constraint for the right table of the
LEFT JOIN.</li>
<li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not
support this function.</li>
}

chng {2007 January 9 (3.3.10)} {
<li>Fix bugs in the implementation of the new 
<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API
that can lead to segfaults.</li>
<li>Fix 1-second round-off errors in the 
<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
strftime()</a> function</li>
<li>Enhance the windows OS layer to provide detailed error codes</li>
<li>Work around a win2k problem so that SQLite can use single-character
database file names</li>
<li>The
<a href="pragma.html#pragma_user_version">user_version</a> and
<a href="pragma.html#pragma_schema_version">schema_version</a> pragmas 
correctly set their column names in the result set</li>
<li>Documentation updates</li>
}

chng {2007 January 4 (3.3.9)} {
<li>Fix bugs in pager.c that could lead to database corruption if two
processes both try to recover a hot journal at the same instant</li>
<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
API.</li>
<li>Fixed the ".dump" command in the command-line shell to show
indices, triggers and views again.</li>
<li>Change the table_info pragma so that it returns NULL for the default
value if there is no default value</li>
<li>Support for non-ASCII characters in win95 filenames</li>
<li>Query optimizer enhancements:
<ul>
<li>Optimizer does a better job of using indices to satisfy ORDER BY
clauses that sort on the integer primary key</li>
<li>Use an index to satisfy an IS NULL operator in the WHERE clause</li>
<li>Fix a bug that was causing the optimizer to miss an OR optimization
opportunity</li>
<li>The optimizer has more freedom to reorder tables in the FROM clause
even in there are LEFT joins.</li>
</ul>
<li>Extension loading supported added to winCE</li>
<li>Allow constraint names on the DEFAULT clause in a table definition</li>
<li>Added the ".bail" command to the command-line shell</li>
<li>Make CSV (comma separate value) output from the command-line shell
more closely aligned to accepted practice</li>
<li>Experimental FTS2 module added</li>
<li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li>
<li>VACUUM uses a temporary file in the official TEMP folder, not in the
same directory as the original database</li>
<li>The prefix on temporary filenames on windows is changed from "sqlite"
to "etilqs".</li>
}

chng {2006 October 9 (3.3.8)} {
<li>Support for full text search using the
<a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a>
(beta)</li>
<li>Added OS-X locking patches (beta - disabled by default)</li>
<li>Introduce extended error codes and add error codes for various
kinds of I/O errors.</li>
<li>Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW</li>
<li>Fix the regression test suite so that it works with Tcl8.5</li>
<li>Enhance sqlite3_set_authorizer() to provide notification of calls to
    SQL functions.</li>
<li>Added experimental API:  sqlite3_auto_extension()</li>
<li>Various minor bug fixes</li>
}

chng {2006 August 12 (3.3.7)} {
<li>Added support for
<a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a>
(beta)</li>
<li>Added support for 
<a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions">
dynamically loaded extensions</a> (beta)</li>
<li>The 
<a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a>
routine can be called for a different thread</li>
<li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li>
<li>The default file format is now 1.  
}

chng {2006 June 6 (3.3.6)} {
<li>Plays better with virus scanners on windows</li>
<li>Faster :memory: databases</li>
<li>Fix an obscure segfault in UTF-8 to UTF-16 conversions</li>
<li>Added driver for OS/2</li>
<li>Correct column meta-information returned for aggregate queries</li>
<li>Enhanced output from EXPLAIN QUERY PLAN</li>
<li>LIMIT 0 now works on subqueries</li>
<li>Bug fixes and performance enhancements in the query optimizer</li>
<li>Correctly handle NULL filenames in ATTACH and DETACH</li>
<li>Inproved syntax error messages in the parser</li>
<li>Fix type coercion rules for the IN operator</li>
}

chng {2006 April 5 (3.3.5)} {
<li>CHECK constraints use conflict resolution algorithms correctly.</li>
<li>The SUM() function throws an error on integer overflow.</li>
<li>Choose the column names in a compound query from the left-most SELECT
    instead of the right-most.</li>
<li>The sqlite3_create_collation() function
    honors the SQLITE_UTF16_ALIGNED flag.</li>
<li>SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite
    old data with zeros.</li>
<li>Detect integer overflow in abs().</li>
<li>The random() function provides 64 bits of randomness instead of
    only 32 bits.</li>
<li>Parser detects and reports automaton stack overflow.</li>
<li>Change the round() function to return REAL instead of TEXT.</li>
<li>Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to
    contain aggregate subqueries.</li>
<li>Skip over leading spaces in text to numeric conversions.</li>
<li>Various minor bug and documentation typo fixes and
    performance enhancements.</li>
}

chng {2006 February 11 (3.3.4)} {
<li>Fix a blunder in the Unix mutex implementation that can lead to
deadlock on multithreaded systems.</li>
<li>Fix an alignment problem on 64-bit machines</li>
<li>Added the fullfsync pragma.</li>
<li>Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs
to give incorrect results.</li>
<li>The SUM function detects integer overflow and converts to accumulating
an approximate result using floating point numbers</li>
<li>Host parameter names can begin with '@' for compatibility with SQL Server.
</li>
<li>Other miscellaneous bug fixes</li>
}

chng {2006 January 31 (3.3.3)} {
<li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never
worked correctly so this should not present any backward compatibility
problems.</li>
<li>Authorizer callback now notified of ALTER TABLE ADD COLUMN commands</li>
<li>After any changes to the TEMP database schema, all prepared statements
are invalidated and must be recreated using a new call to
sqlite3_prepare()</li>
<li>Other minor bug fixes in preparation for the first stable release
of version 3.3</li>
}

chng {2006 January 24 (3.3.2 beta)} {
<li>Bug fixes and speed improvements.  Improved test coverage.</li>
<li>Changes to the OS-layer interface: mutexes must now be recursive.</li>
<li>Discontinue the use of thread-specific data for out-of-memory
exception handling</li>
}

chng {2006 January 16 (3.3.1 alpha)} {
<li>Countless bug fixes</li>
<li>Speed improvements</li>
<li>Database connections can now be used by multiple threads, not just
the thread in which they were created.</li>
}

chng {2006 January 10 (3.3.0 alpha)} {
<li>CHECK constraints</li>
<li>IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.</li>
<li>DESC indices</li>
<li>More efficient encoding of boolean values resulting in smaller database
files</li>
<li>More aggressive SQLITE_OMIT_FLOATING_POINT</li>
<li>Separate INTEGER and REAL affinity</li>
<li>Added a virtual function layer for the OS interface</li>
<li>"exists" method added to the TCL interface</li>
<li>Improved response to out-of-memory errors</li>
<li>Database cache can be optionally shared between connections
in the same thread</li>
<li>Optional READ UNCOMMITTED isolation (instead of the default
isolation level of SERIALIZABLE) and table level locking when
database connections share a common cache.</li>
}

chng {2005 December 19 (3.2.8)} {
<li>Fix an obscure bug that can cause database corruption under the
following unusual circumstances: A large INSERT or UPDATE statement which 
is part of an even larger transaction fails due to a uniqueness contraint
but the containing transaction commits.</li>
}

chng {2005 December 19 (2.8.17)} {
<li>Fix an obscure bug that can cause database corruption under the
following unusual circumstances: A large INSERT or UPDATE statement which 
is part of an even larger transaction fails due to a uniqueness contraint
but the containing transaction commits.</li>
}

chng {2005 September 24 (3.2.7)} {
<li>GROUP BY now considers NULLs to be equal again, as it should
</li>
<li>Now compiles on Solaris and OpenBSD and other Unix variants
that lack the fdatasync() function</li>
<li>Now compiles on MSVC++6 again</li>
<li>Fix uninitialized variables causing malfunctions for various obscure
queries</li>
<li>Correctly compute a LEFT OUTER JOINs that is constrained on the
left table only</li>
}

chng {2005 September 17 (3.2.6)} {
<li>Fix a bug that can cause database corruption if a VACUUM (or
    autovacuum) fails and is rolled back on a database that is
    larger than 1GiB</li>
<li>LIKE optiization now works for columns with COLLATE NOCASE</li>
<li>ORDER BY and GROUP BY now use bounded memory</li>
<li>Added support for COUNT(DISTINCT expr)</li>
<li>Change the way SUM() handles NULL values in order to comply with
    the SQL standard</li>
<li>Use fdatasync() instead of fsync() where possible in order to speed
    up commits slightly</li>
<li>Use of the CROSS keyword in a join turns off the table reordering
    optimization</li>
<li>Added the experimental and undocumented EXPLAIN QUERY PLAN capability</li>
<li>Use the unicode API in windows</li>
}

chng {2005 August 27 (3.2.5)} {
<li>Fix a bug effecting DELETE and UPDATE statements that changed
more than 40960 rows.</li>
<li>Change the makefile so that it no longer requires GNUmake extensions</li>
<li>Fix the --enable-threadsafe option on the configure script</li>
<li>Fix a code generator bug that occurs when the left-hand side of an IN
operator is constant and the right-hand side is a SELECT statement</li>
<li>The PRAGMA synchronous=off statement now disables syncing of the
master journal file in addition to the normal rollback journals</li>
}

chng {2005 August 24 (3.2.4)} {
<li>Fix a bug introduced in the previous release
that can cause a segfault while generating code
for complex WHERE clauses.</li>
<li>Allow floating point literals to begin or end with a decimal point.</li>
}

chng {2005 August 21 (3.2.3)} {
<li>Added support for the CAST operator</li>
<li>Tcl interface allows BLOB values to be transferred to user-defined
functions</li>
<li>Added the "transaction" method to the Tcl interface</li>
<li>Allow the DEFAULT value of a column to call functions that have constant
operands</li>
<li>Added the ANALYZE command for gathering statistics on indices and
using those statistics when picking an index in the optimizer</li>
<li>Remove the limit (formerly 100) on the number of terms in the
WHERE clause</li>
<li>The right-hand side of the IN operator can now be a list of expressions
instead of just a list of constants</li>
<li>Rework the optimizer so that it is able to make better use of indices</li>
<li>The order of tables in a join is adjusted automatically to make
better use of indices</li>
<li>The IN operator is now a candidate for optimization even if the left-hand
side is not the left-most term of the index.  Multiple IN operators can be
used with the same index.</li>
<li>WHERE clause expressions using BETWEEN and OR are now candidates
for optimization</li>
<li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE
compile-time option to set its default value to "on".</li>
<li>Use indices to help with GLOB expressions and LIKE expressions too
when the case_sensitive_like pragma is enabled</li>
<li>Added support for grave-accent quoting for compatibility with MySQL</li>
<li>Improved test coverage</li>
<li>Dozens of minor bug fixes</li>
}

chng {2005 June 13 (3.2.2)} {
<li>Added the sqlite3_db_handle() API</li>
<li>Added the sqlite3_get_autocommit() API</li>
<li>Added a REGEXP operator to the parser.  There is no function to back
up this operator in the standard build but users can add their own using
sqlite3_create_function()</li>
<li>Speed improvements and library footprint reductions.</li>
<li>Fix byte alignment problems on 64-bit architectures.</li>
<li>Many, many minor bug fixes and documentation updates.</li>
}

chng {2005 March 29 (3.2.1)} {
<li>Fix a memory allocation error in the new ADD COLUMN comment.</li>
<li>Documentation updates</li>
}

chng {2005 March 21 (3.2.0)} {
<li>Added support for ALTER TABLE ADD COLUMN.</li>
<li>Added support for the "T" separator in ISO-8601 date/time strings.</li>
<li>Improved support for Cygwin.</li>
<li>Numerous bug fixes and documentation updates.</li>
}

chng {2005 March 16 (3.1.6)} {
<li>Fix a bug that could cause database corruption when inserting
    record into tables with around 125 columns.</li>
<li>sqlite3_step() is now much more likely to invoke the busy handler
    and less likely to return SQLITE_BUSY.</li>
<li>Fix memory leaks that used to occur after a malloc() failure.</li>
}

chng {2005 March 11 (3.1.5)} {
<li>The ioctl on OS-X to control syncing to disk is F_FULLFSYNC,
    not F_FULLSYNC.  The previous release had it wrong.</li>
}

chng {2005 March 10 (3.1.4)} {
<li>Fix a bug in autovacuum that could cause database corruption if
a CREATE UNIQUE INDEX fails because of a constraint violation.
This problem only occurs if the new autovacuum feature introduced in
version 3.1 is turned on.</li>
<li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled
if the synchronous pragma is set to something other than "full".</li>
<li>Add additional forward compatibility to the future version 3.2 database 
file format.</li>
<li>Fix a bug in WHERE clauses of the form (rowid<'2')</li>
<li>New SQLITE_OMIT_... compile-time options added</li>
<li>Updates to the man page</li>
<li>Remove the use of strcasecmp() from the shell</li>
<li>Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init</li>
}

chng {2005 February 19 (3.1.3)} {
<li>Fix a problem with VACUUM on databases from which tables containing
AUTOINCREMENT have been dropped.</li>
<li>Add forward compatibility to the future version 3.2 database file
format.</li>
<li>Documentation updates</li>
}

chng {2005 February 15 (3.1.2)} {
<li>Fix a bug that can lead to database corruption if there are two
open connections to the same database and one connection does a VACUUM
and the second makes some change to the database.</li>
<li>Allow "?" parameters in the LIMIT clause.</li>
<li>Fix VACUUM so that it works with AUTOINCREMENT.</li>
<li>Fix a race condition in AUTOVACUUM that can lead to corrupt databases</li>
<li>Add a numeric version number to the sqlite3.h include file.</li>
<li>Other minor bug fixes and performance enhancements.</li>
}

chng {2005 February 15 (2.8.16)} {
<li>Fix a bug that can lead to database corruption if there are two
open connections to the same database and one connection does a VACUUM
and the second makes some change to the database.</li>
<li>Correctly handle quoted names in CREATE INDEX statements.</li>
<li>Fix a naming conflict between sqlite.h and sqlite3.h.</li>
<li>Avoid excess heap usage when copying expressions.</li>
<li>Other minor bug fixes.</li>
}

chng {2005 February 1 (3.1.1 BETA)} {
<li>Automatic caching of prepared statements in the TCL interface</li>
<li>ATTACH and DETACH as well as some other operations cause existing
    prepared statements to expire.</li>
<li>Numerious minor bug fixes</li>
}

chng {2005 January 21 (3.1.0 ALPHA)} {
<li>Autovacuum support added</li>
<li>CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added</li>
<li>Support for the EXISTS clause added.</li>
<li>Support for correlated subqueries added.</li>
<li>Added the ESCAPE clause on the LIKE operator.</li>
<li>Support for ALTER TABLE ... RENAME TABLE ... added</li>
<li>AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY</li>
<li>Many SQLITE_OMIT_ macros inserts to omit features at compile-time
    and reduce the library footprint.</li>
<li>The REINDEX command was added.</li>
<li>The engine no longer consults the main table if it can get
    all the information it needs from an index.</li>
<li>Many nuisance bugs fixed.</li>
}

chng {2004 October 11 (3.0.8)} {
<li>Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.</li>
<li>Allow new user-defined functions to be created when there are
already one or more precompiled SQL statements.<li>
<li>Fix portability problems for Mingw/MSYS.</li>
<li>Fix a byte alignment problem on 64-bit Sparc machines.</li>
<li>Fix the ".import" command of the shell so that it ignores \r
characters at the end of lines.</li>
<li>The "csv" mode option in the shell puts strings inside double-quotes.</li>
<li>Fix typos in documentation.</li>
<li>Convert array constants in the code to have type "const".</li>
<li>Numerous code optimizations, specially optimizations designed to
make the code footprint smaller.</li>
}

chng {2004 September 18 (3.0.7)} {
<li>The BTree module allocates large buffers using malloc() instead of
    off of the stack, in order to play better on machines with limited
    stack space.</li>
<li>Fixed naming conflicts so that versions 2.8 and 3.0 can be
    linked and used together in the same ANSI-C source file.</li>
<li>New interface: sqlite3_bind_parameter_index()</li>
<li>Add support for wildcard parameters of the form: "?nnn"</li>
<li>Fix problems found on 64-bit systems.</li>
<li>Removed encode.c file (containing unused routines) from the 
    version 3.0 source tree.</li>
<li>The sqlite3_trace() callbacks occur before each statement
    is executed, not when the statement is compiled.</li>
<li>Makefile updates and miscellaneous bug fixes.</li>
}

chng {2004 September 02 (3.0.6 beta)} {
<li>Better detection and handling of corrupt database files.</li>
<li>The sqlite3_step() interface returns SQLITE_BUSY if it is unable
    to commit a change because of a lock</li>
<li>Combine the implementations of LIKE and GLOB into a single
    pattern-matching subroutine.</li>
<li>Miscellaneous code size optimizations and bug fixes</li>
}

chng {2004 August 29 (3.0.5 beta)} {
<li>Support for ":AAA" style bind parameter names.</li>
<li>Added the new sqlite3_bind_parameter_name() interface.</li>
<li>Support for TCL variable names embedded in SQL statements in the
    TCL bindings.</li>
<li>The TCL bindings transfer data without necessarily doing a conversion
    to a string.</li>
<li>The database for TEMP tables is not created until it is needed.</li>
<li>Add the ability to specify an alternative temporary file directory
    using the "sqlite_temp_directory" global variable.</li>
<li>A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy
    handler to be called when there is contention for a RESERVED lock.</li>
<li>Various bug fixes and optimizations</li>
}

chng {2004 August 8 (3.0.4 beta)} {
<li>CREATE TABLE and DROP TABLE now work correctly as prepared statements.</li>
<li>Fix a bug in VACUUM and UNIQUE indices.</li>
<li>Add the ".import" command to the command-line shell.</li>
<li>Fix a bug that could cause index corruption when an attempt to
    delete rows of a table is blocked by a pending query.</li>
<li>Library size optimizations.</li>
<li>Other minor bug fixes.</li>
}

chng {2004 July 22 (2.8.15)} {
<li>This is a maintenance release only.  Various minor bugs have been
fixed and some portability enhancements are added.</li>
}

chng {2004 July 22 (3.0.3 beta)} {
<li>The second beta release for SQLite 3.0.</li>
<li>Add support for "PRAGMA page_size" to adjust the page size of
the database.</li>
<li>Various bug fixes and documentation updates.</li>
}

chng {2004 June 30 (3.0.2 beta)} {
<li>The first beta release for SQLite 3.0.</li>
}

chng {2004 June 22 (3.0.1 alpha)} {
<li><font color="red"><b>
    *** Alpha Release - Research And Testing Use Only ***</b></font>
<li>Lots of bug fixes.</li>
}

chng {2004 June 18 (3.0.0 alpha)} {
<li><font color="red"><b>
    *** Alpha Release - Research And Testing Use Only ***</b></font>
<li>Support for internationalization including UTF-8, UTF-16, and
    user defined collating sequences.</li>
<li>New file format that is 25% to 35% smaller for typical use.</li>
<li>Improved concurrency.</li>
<li>Atomic commits for ATTACHed databases.</li>
<li>Remove cruft from the APIs.</li>
<li>BLOB support.</li>
<li>64-bit rowids.</li>
<li><a href="version3.html">More information</a>.
}

chng {2004 June 9 (2.8.14)} {
<li>Fix the min() and max() optimizer so that it works when the FROM
    clause consists of a subquery.</li>
<li>Ignore extra whitespace at the end of of "." commands in the shell.</li>
<li>Bundle sqlite_encode_binary() and sqlite_decode_binary() with the 
    library.</li>
<li>The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.</li>
<li>Code changes to compile cleanly using OpenWatcom.</li>
<li>Fix VDBE stack overflow problems with INSTEAD OF triggers and
    NULLs in IN operators.</li>
<li>Add the global variable sqlite_temp_directory which if set defines the
    directory in which temporary files are stored.</li>
<li>sqlite_interrupt() plays well with VACUUM.</li>
<li>Other minor bug fixes.</li>
}

chng {2004 March 8 (2.8.13)} {
<li>Refactor parts of the code in order to make the code footprint
    smaller.  The code is now also a little bit faster.</li>
<li>sqlite_exec() is now implemented as a wrapper around sqlite_compile()
    and sqlite_step().</li>
<li>The built-in min() and max() functions now honor the difference between
    NUMERIC and TEXT datatypes.  Formerly, min() and max() always assumed
    their arguments were of type NUMERIC.</li>
<li>New HH:MM:SS modifier to the built-in date/time functions.</li>
<li>Experimental sqlite_last_statement_changes() API added.  Fixed the
    the last_insert_rowid() function so that it works correctly with
    triggers.</li>
<li>Add functions prototypes for the database encryption API.</li>
<li>Fix several nuisance bugs.</li>
}

chng {2004 February 8 (2.8.12)} {
<li>Fix a bug that will might corrupt the rollback journal if a power failure
    or external program halt occurs in the middle of a COMMIT.  The corrupt
    journal can lead to database corruption when it is rolled back.</li>
<li>Reduce the size and increase the speed of various modules, especially
    the virtual machine.</li>
<li>Allow "&lt;expr&gt; IN &lt;table&gt;" as a shorthand for
    "&lt;expr&gt; IN (SELECT * FROM &lt;table&gt;".</li>
<li>Optimizations to the sqlite_mprintf() routine.</li>
<li>Make sure the MIN() and MAX() optimizations work within subqueries.</li>
}

chng {2004 January 14 (2.8.11)} {
<li>Fix a bug in how the IN operator handles NULLs in subqueries.  The bug
    was introduced by the previous release.</li>
}

chng {2004 January 13 (2.8.10)} {
<li>Fix a potential database corruption problem on Unix caused by the fact
    that all posix advisory locks are cleared whenever you close() a file.
    The work around it to embargo all close() calls while locks are 
    outstanding.</li>
<li>Performance enhancements on some corner cases of COUNT(*).</li>
<li>Make sure the in-memory backend response sanely if malloc() fails.</li>
<li>Allow sqlite_exec() to be called from within user-defined SQL
    functions.</li>
<li>Improved accuracy of floating-point conversions using "long double".</li>
<li>Bug fixes in the experimental date/time functions.</li>
}

chng {2004 January 5 (2.8.9)} {
<li>Fix a 32-bit integer overflow problem that could result in corrupt
    indices in a database if large negative numbers (less than -2147483648)
    were inserted into a indexed numeric column.</li>
<li>Fix a locking problem on multi-threaded Linux implementations.</li>
<li>Always use "." instead of "," as the decimal point even if the locale
    requests ",".</li>
<li>Added UTC to localtime conversions to the experimental date/time
    functions.</li>
<li>Bug fixes to date/time functions.</li>
}

chng {2003 December 17 (2.8.8)} {
<li>Fix a critical bug introduced into 2.8.0 which could cause
    database corruption.</li>
<li>Fix a problem with 3-way joins that do not use indices</li>
<li>The VACUUM command now works with the non-callback API</li>
<li>Improvements to the "PRAGMA integrity_check" command</li>
}

chng {2003 December 4 (2.8.7)} {
<li>Added experimental sqlite_bind() and sqlite_reset() APIs.</li>
<li>If the name of the database is an empty string, open a new database
    in a temporary file that is automatically deleted when the database
    is closed.</li>
<li>Performance enhancements in the lemon-generated parser</li>
<li>Experimental date/time functions revised.</li>
<li>Disallow temporary indices on permanent tables.</li>
<li>Documentation updates and typo fixes</li>
<li>Added experimental sqlite_progress_handler() callback API</li>
<li>Removed support for the Oracle8 outer join syntax.</li>
<li>Allow GLOB and LIKE operators to work as functions.</li>
<li>Other minor documentation and makefile changes and bug fixes.</li>
}

chng {2003 August 21 (2.8.6)} {
<li>Moved the CVS repository to www.sqlite.org</li>
<li>Update the NULL-handling documentation.</li>
<li>Experimental date/time functions added.</li>
<li>Bug fix: correctly evaluate a view of a view without segfaulting.</li>
<li>Bug fix: prevent database corruption if you dropped a
    trigger that had the same name as a table.</li>
<li>Bug fix: allow a VACUUM (without segfaulting) on an empty
    database after setting the EMPTY_RESULT_CALLBACKS pragma.</li>
<li>Bug fix: if an integer value will not fit in a 32-bit int, store it in
    a double instead.</li>
<li>Bug fix: Make sure the journal file directory entry is committed to disk
    before writing the database file.</li>
}

chng {2003 July 22 (2.8.5)} {
<li>Make LIMIT work on a compound SELECT statement.</li>
<li>LIMIT 0 now shows no rows.  Use LIMIT -1 to see all rows.</li>
<li>Correctly handle comparisons between an INTEGER PRIMARY KEY and
    a floating point number.</li>
<li>Fix several important bugs in the new ATTACH and DETACH commands.</li>
<li>Updated the <a href="nulls.html">NULL-handling document</a>.</li> 
<li>Allow NULL arguments in sqlite_compile() and sqlite_step().</li>
<li>Many minor bug fixes</li>
}

chng {2003 June 29 (2.8.4)} {
<li>Enhanced the "PRAGMA integrity_check" command to verify indices.</li>
<li>Added authorization hooks for the new ATTACH and DETACH commands.</li>
<li>Many documentation updates</li>
<li>Many minor bug fixes</li>
}

chng {2003 June 4 (2.8.3)} {
<li>Fix a problem that will corrupt the indices on a table if you
    do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that
    contains an INTEGER PRIMARY KEY plus one or more indices.</li>
<li>Fix a bug in windows locking code so that locks work correctly
    when simultaneously accessed by Win95 and WinNT systems.</li>
<li>Add the ability for INSERT and UPDATE statements to refer to the
    "rowid" (or "_rowid_" or "oid") columns.</li>
<li>Other important bug fixes</li>
}

chng {2003 May 17 (2.8.2)} {
<li>Fix a problem that will corrupt the database file if you drop a
    table from the main database that has a TEMP index.</li>
}

chng {2003 May 16 (2.8.1)} {
<li>Reactivated the VACUUM command that reclaims unused disk space in 
    a database file.</li>
<li>Added the ATTACH and DETACH commands to allow interacting with multiple
    database files at the same time.</li>
<li>Added support for TEMP triggers and indices.</li>
<li>Added support for in-memory databases.</li>
<li>Removed the experimental sqlite_open_aux_file().  Its function is
    subsumed in the new ATTACH command.</li>
<li>The precedence order for ON CONFLICT clauses was changed so that
    ON CONFLICT clauses on BEGIN statements have a higher precedence than
    ON CONFLICT clauses on constraints.
<li>Many, many bug fixes and compatibility enhancements.</li>
}

chng {2003 Feb 16 (2.8.0)} {
<li>Modified the journal file format to make it more resistant to corruption
    that can occur after an OS crash or power failure.</li>
<li>Added a new C/C++ API that does not use callback for returning data.</li>
}

chng {2003 Jan 25 (2.7.6)} {
<li>Performance improvements.  The library is now much faster.</li>
<li>Added the <b>sqlite_set_authorizer()</b> API.  Formal documentation has
    not been written - see the source code comments for instructions on
    how to use this function.</li>
<li>Fix a bug in the GLOB operator that was preventing it from working
    with upper-case letters.</li>
<li>Various minor bug fixes.</li>
}

chng {2002 Dec 27 (2.7.5)} {
<li>Fix an uninitialized variable in pager.c which could (with a probability
    of about 1 in 4 billion) result in a corrupted database.</li>
}

chng {2002 Dec 17 (2.7.4)} {
<li>Database files can now grow to be up to 2^41 bytes.  The old limit
    was 2^31 bytes.</li>
<li>The optimizer will now scan tables in the reverse if doing so will
    satisfy an ORDER BY ... DESC clause.</li>
<li>The full pathname of the database file is now remembered even if
    a relative path is passed into sqlite_open().  This allows 
    the library to continue operating correctly after a chdir().</li>
<li>Speed improvements in the VDBE.</li>
<li>Lots of little bug fixes.</li>
}

chng {2002 Oct 30 (2.7.3)} {
<li>Various compiler compatibility fixes.</li>
<li>Fix a bug in the "expr IN ()" operator.</li>
<li>Accept column names in parentheses.</li>
<li>Fix a problem with string memory management in the VDBE</li>
<li>Fix a bug in the "table_info" pragma"</li>
<li>Export the sqlite_function_type() API function in the Windows DLL</li>
<li>Fix locking behavior under windows</li>
<li>Fix a bug in LEFT OUTER JOIN</li>
}

chng {2002 Sep 25 (2.7.2)} {
<li>Prevent journal file overflows on huge transactions.</li>
<li>Fix a memory leak that occurred when sqlite_open() failed.</li>
<li>Honor the ORDER BY and LIMIT clause of a SELECT even if the
    result set is used for an INSERT.</li>
<li>Do not put write locks on the file used to hold TEMP tables.</li>
<li>Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.</li>
<li>Fix a problem that was causing poor performance when many thousands
    of SQL statements were executed by a single sqlite_exec() call.</li>
}

chng {2002 Aug 31 (2.7.1)} {
<li>Fix a bug in the ORDER BY logic that was introduced in version 2.7.0</li>
<li>C-style comments are now accepted by the tokenizer.</li>
<li>INSERT runs a little faster when the source is a SELECT statement.</li>
}

chng {2002 Aug 25 (2.7.0)} {
<li>Make a distinction between numeric and text values when sorting.
    Text values sort according to memcmp().  Numeric values sort in
    numeric order.</li>
<li>Allow multiple simultaneous readers under windows by simulating
    the reader/writers locks that are missing from Win95/98/ME.</li>
<li>An error is now returned when trying to start a transaction if
    another transaction is already active.</li>
}

chng {2002 Aug 12 (2.6.3)} {
<li>Add the ability to read both little-endian and big-endian databases.
    So database created under SunOS or MacOSX can be read and written
    under Linux or Windows and vice versa.</li>
<li>Convert to the new website: http://www.sqlite.org/</li>
<li>Allow transactions to span Linux Threads</li>
<li>Bug fix in the processing of the ORDER BY clause for GROUP BY queries</li>
}

chng {2002 Jly 30 (2.6.2)} {
<li>Text files read by the COPY command can now have line terminators
    of LF,  CRLF, or CR.</li>
<li>SQLITE_BUSY is handled correctly if encountered during database
    initialization.</li>
<li>Fix to UPDATE triggers on TEMP tables.</li>
<li>Documentation updates.</li>
}

chng {2002 Jly 19 (2.6.1)} {
<li>Include a static string in the library that responds to the RCS
    "ident" command and which contains the library version number.</li>
<li>Fix an assertion failure that occurred when deleting all rows of
    a table with the "count_changes" pragma turned on.</li>
<li>Better error reporting when problems occur during the automatic
    2.5.6 to 2.6.0 database format upgrade.</li>
}

chng {2002 Jly 17 (2.6.0)} {
<li>Change the format of indices to correct a design flaw the originated
    with version 2.1.0.  <font color="red">*** This is an incompatible
    file format change ***</font>  When version 2.6.0 or later of the
    library attempts to open a database file created by version 2.5.6 or
    earlier, it will automatically and irreversibly convert the file format.
    <b>Make backup copies of older database files before opening them with
    version 2.6.0 of the library.</b>
    </li>
}

chng {2002 Jly 7 (2.5.6)} {
<li>Fix more problems with rollback.  Enhance the test suite to exercise
    the rollback logic extensively in order to prevent any future problems.
    </li>
}

chng {2002 Jly 6 (2.5.5)} {
<li>Fix a bug which could cause database corruption during a rollback.
    This bugs was introduced in version 2.4.0 by the freelist
    optimization of checking [410].</li>
<li>Fix a bug in aggregate functions for VIEWs.</li>
<li>Other minor changes and enhancements.</li>
}

chng {2002 Jly 1 (2.5.4)} {
<li>Make the "AS" keyword optional again.</li>
<li>The datatype of columns now appear in the 4th argument to the
    callback.</li>
<li>Added the <b>sqlite_open_aux_file()</b> API, though it is still
    mostly undocumented and untested.</li>
<li>Added additional test cases and fixed a few bugs that those
    test cases found.</li>
}

chng {2002 Jun 24 (2.5.3)} {
<li>Bug fix:  Database corruption can occur due to the optimization
    that was introduced in version 2.4.0 (check-in [410]).  The problem
    should now be fixed.  The use of versions 2.4.0 through 2.5.2 is
    not recommended.</li>
}

chng {2002 Jun 24 (2.5.2)} {
<li>Added the new <b>SQLITE_TEMP_MASTER</b> table which records the schema
    for temporary tables in the same way that <b>SQLITE_MASTER</b> does for
    persistent tables.</li>
<li>Added an optimization to UNION ALL</li>
<li>Fixed a bug in the processing of LEFT OUTER JOIN</li>
<li>The LIMIT clause now works on subselects</li>
<li>ORDER BY works on subselects</li>
<li>There is a new TypeOf() function used to determine if an expression
    is numeric or text.</li>
<li>Autoincrement now works for INSERT from a SELECT.</li>
}

chng {2002 Jun 19 (2.5.1)} {
<li>The query optimizer now attempts to implement the ORDER BY clause
    using an index.  Sorting is still used if not suitable index is
    available.</li>
}

chng {2002 Jun 17 (2.5.0)} {
<li>Added support for row triggers.</li>
<li>Added SQL-92 compliant handling of NULLs.</li>
<li>Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.</li>
<li>Double-quoted strings interpreted as column names not text literals.</li>
<li>Parse (but do not implement) foreign keys.</li>
<li>Performance improvements in the parser, pager, and WHERE clause code
    generator.</li>
<li>Make the LIMIT clause work on subqueries.  (ORDER BY still does not
    work, though.)</li>
<li>Added the "%Q" expansion to sqlite_*_printf().</li>
<li>Bug fixes too numerous to mention (see the change log).</li>
}

chng {2002 May 09 (2.4.12)} {
<li>Added logic to detect when the library API routines are called out
    of sequence.</li>
}

chng {2002 May 08 (2.4.11)} {
<li>Bug fix: Column names in the result set were not being generated
    correctly for some (rather complex) VIEWs.  This could cause a
    segfault under certain circumstances.</li>
}

chng {2002 May 02 (2.4.10)} {
<li>Bug fix: Generate correct column headers when a compound SELECT is used
    as a subquery.</li>
<li>Added the sqlite_encode_binary() and sqlite_decode_binary() functions to
    the source tree.  But they are not yet linked into the library.</li>
<li>Documentation updates.</li>
<li>Export the sqlite_changes() function from windows DLLs.</li>
<li>Bug fix: Do not attempt the subquery flattening optimization on queries
    that lack a FROM clause.  To do so causes a segfault.</li>
}

chng {2002 Apr 21 (2.4.9)} {
<li>Fix a bug that was causing the precompiled binary of SQLITE.EXE to
    report "out of memory" under Windows 98.</li>
}

chng {2002 Apr 20 (2.4.8)} {
<li>Make sure VIEWs are created after their corresponding TABLEs in the
    output of the <b>.dump</b> command in the shell.</li>
<li>Speed improvements: Do not do synchronous updates on TEMP tables.</li>
<li>Many improvements and enhancements to the shell.</li>
<li>Make the GLOB and LIKE operators functions that can be overridden
    by a programmer.  This allows, for example, the LIKE operator to
    be changed to be case sensitive.</li>
}

chng {2002 Apr 06 (2.4.7)} {
<li>Add the ability to put TABLE.* in the column list of a
    SELECT statement.</li>
<li>Permit SELECT statements without a FROM clause.</li>
<li>Added the <b>last_insert_rowid()</b> SQL function.</li>
<li>Do not count rows where the IGNORE conflict resolution occurs in
    the row count.</li>
<li>Make sure functions expressions in the VALUES clause of an INSERT
    are correct.</li>
<li>Added the <b>sqlite_changes()</b> API function to return the number
    of row that changed in the most recent operation.</li>
}

chng {2002 Apr 02 (2.4.6)} {
<li>Bug fix: Correctly handle terms in the WHERE clause of a join that
    do not contain a comparison operator.</li>
}

chng {2002 Apr 01 (2.4.5)} {
<li>Bug fix: Correctly handle functions that appear in the WHERE clause
    of a join.</li>
<li>When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand
    value when it is a pointer to a structure rather than a pointer to
    a string.</li>
<li>When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert
    the NULL value into a unique key automatically.</li>
}

chng {2002 Mar 24 (2.4.4)} {
<li>Allow "VIEW" to be a column name</li>
<li>Added support for CASE expressions (patch from Dan Kennedy)</li>
<li>Added RPMS to the delivery (patches from Doug Henry)</li>
<li>Fix typos in the documentation</li>
<li>Cut over configuration management to a new CVS repository with
    its own CVSTrac bug tracking system.</li>
}

chng {2002 Mar 22 (2.4.3)} {
<li>Fix a bug in SELECT that occurs when a compound SELECT is used as a
    subquery in the FROM of a SELECT.</li>
<li>The <b>sqlite_get_table()</b> function now returns an error if you
    give it two or more SELECTs that return different numbers of columns.</li>
}

chng {2002 Mar 14 (2.4.2)} {
<li>Bug fix: Fix an assertion failure that occurred when ROWID was a column
    in a SELECT statement on a view.</li>
<li>Bug fix: Fix an uninitialized variable in the VDBE that would could an
    assert failure.</li>
<li>Make the os.h header file more robust in detecting when the compile is
    for windows and when it is for unix.</li>
}

chng {2002 Mar 13 (2.4.1)} {
<li>Using an unnamed subquery in a FROM clause would cause a segfault.</li>
<li>The parser now insists on seeing a semicolon or the end of input before
    executing a statement.  This avoids an accidental disaster if the
    WHERE keyword is misspelled in an UPDATE or DELETE statement.</li>
}


chng {2002 Mar 10 (2.4.0)} {
<li>Change the name of the sanity_check PRAGMA to <b>integrity_check</b>
    and make it available in all compiles.</li>
<li>SELECT min() or max() of an indexed column with no WHERE or GROUP BY
    clause is handled as a special case which avoids a complete table scan.</li>
<li>Automatically generated ROWIDs are now sequential.</li>
<li>Do not allow dot-commands of the command-line shell to occur in the
    middle of a real SQL command.</li>
<li>Modifications to the "lemon" parser generator so that the parser tables
    are 4 times smaller.</li>
<li>Added support for user-defined functions implemented in C.</li>
<li>Added support for new functions: <b>coalesce()</b>, <b>lower()</b>,
    <b>upper()</b>, and <b>random()</b>
<li>Added support for VIEWs.</li>
<li>Added the subquery flattening optimizer.</li>
<li>Modified the B-Tree and Pager modules so that disk pages that do not
    contain real data (free pages) are not journaled and are not
    written from memory back to the disk when they change.  This does not 
    impact database integrity, since the
    pages contain no real data, but it does make large INSERT operations
    about 2.5 times faster and large DELETEs about 5 times faster.</li>
<li>Made the CACHE_SIZE pragma persistent</li>
<li>Added the SYNCHRONOUS pragma</li>
<li>Fixed a bug that was causing updates to fail inside of transactions when
    the database contained a temporary table.</li>
}

chng {2002 Feb 18 (2.3.3)} {
<li>Allow identifiers to be quoted in square brackets, for compatibility
    with MS-Access.</li>
<li>Added support for sub-queries in the FROM clause of a SELECT.</li>
<li>More efficient implementation of sqliteFileExists() under Windows.
    (by Joel Luscy)</li>
<li>The VALUES clause of an INSERT can now contain expressions, including
    scalar SELECT clauses.</li>
<li>Added support for CREATE TABLE AS SELECT</li>
<li>Bug fix: Creating and dropping a table all within a single
    transaction was not working.</li>
}

chng {2002 Feb 14 (2.3.2)} {
<li>Bug fix: There was an incorrect assert() in pager.c.  The real code was
    all correct (as far as is known) so everything should work OK if you
    compile with -DNDEBUG=1.  When asserts are not disabled, there
    could be a fault.</li>
}

chng {2002 Feb 13 (2.3.1)} {
<li>Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was
    set and you did a query that used a rowid, like this:  
    "SELECT rowid, * FROM ...".</li>
}

chng {2002 Jan 30 (2.3.0)} {
<li>Fix a serious bug in the INSERT command which was causing data to go
    into the wrong columns if the data source was a SELECT and the INSERT
    clauses specified its columns in some order other than the default.</li>
<li>Added the ability to resolve constraint conflicts is ways other than
    an abort and rollback.  See the documentation on the "ON CONFLICT"
    clause for details.</li>
<li>Temporary files are now automatically deleted by the operating system
    when closed.  There are no more dangling temporary files on a program
    crash.  (If the OS crashes, fsck will delete the file after reboot 
    under Unix.  I do not know what happens under Windows.)</li>
<li>NOT NULL constraints are honored.</li>
<li>The COPY command puts NULLs in columns whose data is '\N'.</li>
<li>In the COPY command, backslash can now be used to escape a newline.</li>
<li>Added the SANITY_CHECK pragma.</li>
}

chng {2002 Jan 28 (2.2.5)} {
<li>Important bug fix: the IN operator was not working if either the
    left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.</li>
<li>Do not escape the backslash '\' character in the output of the
    <b>sqlite</b> command-line access program.</li>
}

chng {2002 Jan 22 (2.2.4)} {
<li>The label to the right of an AS in the column list of a SELECT can now
    be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or
    HAVING clauses.</li>
<li>Fix a bug in the <b>-separator</b> command-line option to the <b>sqlite</b>
    command.</li>
<li>Fix a problem with the sort order when comparing upper-case strings against
    characters greater than 'Z' but less than 'a'.</li>
<li>Report an error if an ORDER BY or GROUP BY expression is constant.</li>
}

chng {2002 Jan 16 (2.2.3)} {
<li>Fix warning messages in VC++ 7.0.  (Patches from nicolas352001)</li>
<li>Make the library thread-safe.  (The code is there and appears to work
    but has not been stressed.)</li>
<li>Added the new <b>sqlite_last_insert_rowid()</b> API function.</li>
}

chng {2002 Jan 13 (2.2.2)} {
<li>Bug fix: An assertion was failing when a temporary table with an index
    had the same name as a permanent table created by a separate process.</li>
<li>Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an
    index could fail.</li>
}

chng {2002 Jan 9 (2.2.1)} {
<li>Bug fix: An attempt to delete a single row of a table with a WHERE
    clause of "ROWID=x" when no such rowid exists was causing an error.</li>
<li>Bug fix: Passing in a NULL as the 3rd parameter to <b>sqlite_open()</b>
    would sometimes cause a coredump.</li>
<li>Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all
    within a single transaction was causing a coredump.</li>
<li>Makefile updates from A. Rottmann</li>
}

chng {2001 Dec 22 (2.2.0)} {
<li>Columns of type INTEGER PRIMARY KEY are actually used as the primary
    key in underlying B-Tree representation of the table.</li>
<li>Several obscure, unrelated bugs were found and fixed while 
    implemented the integer primary key change of the previous bullet.</li>
<li>Added the ability to specify "*" as part of a larger column list in
    the result section of a SELECT statement.  For example:
    <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li>
<li>Updates to comments and documentation.</li>
}

chng {2001 Dec 14 (2.1.7)} {
<li>Fix a bug in <b>CREATE TEMPORARY TABLE</b> which was causing the
    table to be initially allocated in the main database file instead
    of in the separate temporary file.  This bug could cause the library
    to suffer an assertion failure and it could cause "page leaks" in the
    main database file.
<li>Fix a bug in the b-tree subsystem that could sometimes cause the first
    row of a table to be repeated during a database scan.</li>
}

chng {2001 Dec 14 (2.1.6)} {
<li>Fix the locking mechanism yet again to prevent
    <b>sqlite_exec()</b> from returning SQLITE_PROTOCOL
    unnecessarily.  This time the bug was a race condition in
    the locking code.  This change effects both POSIX and Windows users.</li>
}

chng {2001 Dec 6 (2.1.5)} {
<li>Fix for another problem (unrelated to the one fixed in 2.1.4) 
    that sometimes causes <b>sqlite_exec()</b> to return SQLITE_PROTOCOL
    unnecessarily.  This time the bug was
    in the POSIX locking code and should not effect windows users.</li>
}

chng {2001 Dec 4 (2.1.4)} {
<li>Sometimes <b>sqlite_exec()</b> would return SQLITE_PROTOCOL when it
    should have returned SQLITE_BUSY.</li>
<li>The fix to the previous bug uncovered a deadlock which was also
    fixed.</li>
<li>Add the ability to put a single .command in the second argument
    of the sqlite shell</li>
<li>Updates to the FAQ</li>
}

chng {2001 Nov 23 (2.1.3)} {
<li>Fix the behavior of comparison operators 
    (ex: "<b>&lt</b>", "<b>==</b>", etc.)
    so that they are consistent with the order of entries in an index.</li>
<li>Correct handling of integers in SQL expressions that are larger than
    what can be represented by the machine integer.</li>
}

chng {2001 Nov 22 (2.1.2)} {
<li>Changes to support 64-bit architectures.</li>
<li>Fix a bug in the locking protocol.</li>
<li>Fix a bug that could (rarely) cause the database to become 
    unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER
    table.</li>
<li>Change the code so that version 2.1.1 databases that were rendered 
    unreadable by the above bug can be read by this version of
    the library even though the SQLITE_MASTER table is (slightly)
    corrupted.</li>
}

chng {2001 Nov 13 (2.1.1)} {
<li>Bug fix: Sometimes arbitrary strings were passed to the callback
    function when the actual value of a column was NULL.</li>
}

chng {2001 Nov 12 (2.1.0)} {
<li>Change the format of data records so that records up to 16MB in size
    can be stored.</li>
<li>Change the format of indices to allow for better query optimization.</li>
<li>Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.</li>
}

chng {2001 Nov 3 (2.0.8)} {
<li>Made selected parameters in API functions <b>const</b>. This should
    be fully backwards compatible.</li>
<li>Documentation updates</li>
<li>Simplify the design of the VDBE by restricting the number of sorters
    and lists to 1.
    In practice, no more than one sorter and one list was ever used anyhow.
    </li>
}

chng {2001 Oct 21 (2.0.7)} {
<li>Any UTF-8 character or ISO8859 character can be used as part of
    an identifier.</li>
<li>Patches from Christian Werner to improve ODBC compatibility and to
    fix a bug in the round() function.</li>
<li>Plug some memory leaks that use to occur if malloc() failed.
    We have been and continue to be memory leak free as long as
    malloc() works.</li>
<li>Changes to some test scripts so that they work on Windows in
    addition to Unix.</li>
}

chng {2001 Oct 19 (2.0.6)} {
<li>Added the EMPTY_RESULT_CALLBACKS pragma</li>
<li>Support for UTF-8 and ISO8859 characters in column and table names.</li>
<li>Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma
    is turned on.</li>
}

chng {2001 Oct 14 (2.0.5)} {
<li>Added the COUNT_CHANGES pragma.</li>
<li>Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.</li>
<li>Bug fix: "SELECT count(*)" was returning NULL for empty tables.
    Now it returns 0.</li>
}

chng {2001 Oct 13 (2.0.4)} {
<li>Bug fix: an obscure and relatively harmless bug was causing one of
    the tests to fail when gcc optimizations are turned on.  This release
    fixes the problem.</li>
}

chng {2001 Oct 13 (2.0.3)} {
<li>Bug fix: the <b>sqlite_busy_timeout()</b> function was delaying 1000
    times too long before failing.</li>
<li>Bug fix: an assertion was failing if the disk holding the database
    file became full or stopped accepting writes for some other reason.
    New tests were added to detect similar problems in the future.</li>
<li>Added new operators: <b>&amp;</b> (bitwise-and)
    <b>|</b> (bitwise-or), <b>~</b> (ones-complement),
    <b>&lt;&lt;</b> (shift left), <b>&gt;&gt;</b> (shift right).</li>
<li>Added new functions: <b>round()</b> and <b>abs()</b>.</li>
}

chng {2001 Oct 9 (2.0.2)} {
<li>Fix two bugs in the locking protocol.  (One was masking the other.)</li>
<li>Removed some unused "#include <unistd.h>" that were causing problems
    for VC++.</li>
<li>Fixed <b>sqlite.h</b> so that it is usable from C++</li>
<li>Added the FULL_COLUMN_NAMES pragma.  When set to "ON", the names of
    columns are reported back as TABLE.COLUMN instead of just COLUMN.</li>
<li>Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the
    ODBC interface.</li>
<li>Added support for TEMPORARY tables and indices.</li>
}

chng {2001 Oct 2 (2.0.1)} {
<li>Remove some C++ style comments from btree.c so that it will compile
    using compilers other than gcc.</li>
<li>The ".dump" output from the shell does not work if there are embedded
    newlines anywhere in the data.  This is an old bug that was carried
    forward from version 1.0.  To fix it, the ".dump" output no longer
    uses the COPY command.  It instead generates INSERT statements.</li>
<li>Extend the expression syntax to support "expr NOT NULL" (with a
    space between the "NOT" and the "NULL") in addition to "expr NOTNULL"
    (with no space).</li>
}

chng {2001 Sep 28 (2.0.0)} {
<li>Automatically build binaries for Linux and Windows and put them on
    the website.</li>
}

chng {2001 Sep 28 (2.0-alpha-4)} {
<li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li>
}

chng {2001 Sep 27 (2.0-alpha-3)} {
<li>SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX.  Primary
    keys are required to be unique.</li>
<li>File format changed back to what it was for alpha-1</li>
<li>Fixes to the rollback and locking behavior</li>
}

chng {2001 Sep 20 (2.0-alpha-2)} {
<li>Initial release of version 2.0.  The idea of renaming the library
    to "SQLus" was abandoned in favor of keeping the "SQLite" name and
    bumping the major version number.</li>
<li>The pager and btree subsystems added back. They are now the only
    available backend.</li>
<li>The Dbbe abstraction and the GDBM and memory drivers were removed.</li>
<li>Copyright on all code was disclaimed.  The library is now in the
    public domain.</li>
}

chng {2001 Jul 23 (1.0.32)} {
<li>Pager and btree subsystems removed.  These will be used in a follow-on
    SQL server library named "SQLus".</li>
<li>Add the ability to use quoted strings as table and column names in
    expressions.</li>
}

chng {2001 Apr 14 (1.0.31)} {
<li>Pager subsystem added but not yet used.</li>
<li>More robust handling of out-of-memory errors.</li>
<li>New tests added to the test suite.</li>
}

chng {2001 Apr 6 (1.0.30)} {
<li>Remove the <b>sqlite_encoding</b> TCL variable that was introduced
    in the previous version.</li>
<li>Add options <b>-encoding</b> and <b>-tcl-uses-utf</b> to the
    <b>sqlite</b> TCL command.</li>
<li>Add tests to make sure that tclsqlite was compiled using Tcl header
    files and libraries that match.</li>
}

chng {2001 Apr 5 (1.0.29)} {
<li>The library now assumes data is stored as UTF-8 if the --enable-utf8
    option is given to configure.  The default behavior is to assume
    iso8859-x, as it has always done.  This only makes a difference for
    LIKE and GLOB operators and the LENGTH and SUBSTR functions.</li>
<li>If the library is not configured for UTF-8 and the Tcl library
    is one of the newer ones that uses UTF-8 internally,
    then a conversion from UTF-8 to iso8859 and
    back again is done inside the TCL interface.</li>
}

chng {2001 Apr 4 (1.0.28)} {
<li>Added limited support for transactions.  At this point, transactions
    will do table locking on the GDBM backend.  There is no support (yet)
    for rollback or atomic commit.</li>
<li>Added special column names ROWID, OID, and _ROWID_ that refer to the
    unique random integer key associated with every row of every table.</li>
<li>Additional tests added to the regression suite to cover the new ROWID
    feature and the TCL interface bugs mentioned below.</li>
<li>Changes to the "lemon" parser generator to help it work better when
    compiled using MSVC.</li>
<li>Bug fixes in the TCL interface identified by Oleg Oleinick.</li>
}

chng {2001 Mar 20 (1.0.27)} {
<li>When doing DELETE and UPDATE, the library used to write the record
    numbers of records to be deleted or updated into a temporary file.
    This is changed so that the record numbers are held in memory.</li>
<li>The DELETE command without a WHILE clause just removes the database
    files from the disk, rather than going through and deleting record
    by record.</li>
}

chng {2001 Mar 20 (1.0.26)} {
<li>A serious bug fixed on Windows.  Windows users should upgrade.
    No impact to Unix.</li>
}

chng {2001 Mar 15 (1.0.25)} {
<li>Modify the test scripts to identify tests that depend on system
    load and processor speed and
    to warn the user that a failure of one of those (rare) tests does
    not necessarily mean the library is malfunctioning.  No changes to
    code.
    </li>
}

chng {2001 Mar 14 (1.0.24)} {
<li>Fix a bug which was causing
    the UPDATE command to fail on systems where "malloc(0)" returns
    NULL.  The problem does not appear Windows, Linux, or HPUX but does 
    cause the library to fail on QNX.
    </li>
}

chng {2001 Feb 19 (1.0.23)} {
<li>An unrelated (and minor) bug from Mark Muranwski fixed.  The algorithm
    for figuring out where to put temporary files for a "memory:" database
    was not working quite right.
    </li>
}

chng {2001 Feb 19 (1.0.22)} {
<li>The previous fix was not quite right.  This one seems to work better.
    </li>
}

chng {2001 Feb 19 (1.0.21)} {
<li>The UPDATE statement was not working when the WHERE clause contained
    some terms that could be satisfied using indices and other terms that
    could not.  Fixed.</li>
}

chng {2001 Feb 11 (1.0.20)} {
<li>Merge development changes into the main trunk.  Future work toward
    using a BTree file structure will use a separate CVS source tree.  This
    CVS tree will continue to support the GDBM version of SQLite only.</li>
}

chng {2001 Feb 6 (1.0.19)} {
<li>Fix a strange (but valid) C declaration that was causing problems
    for QNX.  No logical changes.</li>
}

chng {2001 Jan 4 (1.0.18)} {
<li>Print the offending SQL statement when an error occurs.</li>
<li>Do not require commas between constraints in CREATE TABLE statements.</li>
<li>Added the "-echo" option to the shell.</li>
<li>Changes to comments.</li>
}

chng {2000 Dec 10 (1.0.17)} {
<li>Rewrote <b>sqlite_complete()</b> to make it faster.</li>
<li>Minor tweaks to other code to make it run a little faster.</li>
<li>Added new tests for <b>sqlite_complete()</b> and for memory leaks.</li>
}

chng {2000 Dec 4 (1.0.16)} {
<li>Documentation updates.  Mostly fixing of typos and spelling errors.</li>
}

chng {2000 Oct 23 (1.0.15)} {
<li>Documentation updates</li>
<li>Some sanity checking code was removed from the inner loop of vdbe.c
    to help the library to run a little faster.  The code is only
    removed if you compile with -DNDEBUG.</li>
}

chng {2000 Oct 19 (1.0.14)} {
<li>Added a "memory:" backend driver that stores its database in an
    in-memory hash table.</li>
}

chng {2000 Oct 18 (1.0.13)} {
<li>Break out the GDBM driver into a separate file in anticipation
    to added new drivers.</li>
<li>Allow the name of a database to be prefixed by the driver type.
    For now, the only driver type is "gdbm:".</li>
}

chng {2000 Oct 16 (1.0.12)} {
<li>Fixed an off-by-one error that was causing a coredump in 
    the '%q' format directive of the new
    <b>sqlite_..._printf()</b> routines.</li>
<li>Added the <b>sqlite_interrupt()</b> interface.</li>
<li>In the shell, <b>sqlite_interrupt()</b> is invoked when the
    user presses Control-C</li>
<li>Fixed some instances where <b>sqlite_exec()</b> was
    returning the wrong error code.</li>
}

chng {2000 Oct 11 (1.0.10)} {
<li>Added notes on how to compile for Windows95/98.</li>
<li>Removed a few variables that were not being used.  Etc.</li>
}

chng {2000 Oct 8 (1.0.9)} {
<li>Added the <b>sqlite_..._printf()</b> interface routines.</li>
<li>Modified the <b>sqlite</b> shell program to use the new interface 
    routines.</li>
<li>Modified the <b>sqlite</b> shell program to print the schema for
    the built-in SQLITE_MASTER table, if explicitly requested.</li>
}

chng {2000 Sep 30 (1.0.8)} {
<li>Begin writing documentation on the TCL interface.</li>
}

chng {2000 Sep 29 (Not Released)} {
<li>Added the <b>sqlite_get_table()</b> API</li>
<li>Updated the documentation for due to the above change.</li>
<li>Modified the <b>sqlite</b> shell to make use of the new
    sqlite_get_table() API in order to print a list of tables
    in multiple columns, similar to the way "ls" prints filenames.</li>
<li>Modified the <b>sqlite</b> shell to print a semicolon at the
    end of each CREATE statement in the output of the ".schema" command.</li>
}

chng {2000 Sep 21 (Not Released)} {
<li>Change the tclsqlite "eval" method to return a list of results if
    no callback script is specified.</li>
<li>Change tclsqlite.c to use the Tcl_Obj interface</li>
<li>Add tclsqlite.c to the libsqlite.a library</li>
}

chng {2000 Sep 13 (Version 1.0.5)} {
<li>Changed the print format for floating point values from "%g" to "%.15g".
    </li>
<li>Changed the comparison function so that numbers in exponential notation
    (ex: 1.234e+05) sort in numerical order.</li>
}

chng {2000 Aug 28 (Version 1.0.4)} {
<li>Added functions <b>length()</b> and <b>substr()</b>.</li>
<li>Fix a bug in the <b>sqlite</b> shell program that was causing
    a coredump when the output mode was "column" and the first row
    of data contained a NULL.</li>
}

chng {2000 Aug 22 (Version 1.0.3)} {
<li>In the sqlite shell, print the "Database opened READ ONLY" message
    to stderr instead of stdout.</li>
<li>In the sqlite shell, now print the version number on initial startup.</li>
<li>Add the <b>sqlite_version[]</b> string constant to the library</li>
<li>Makefile updates</li>
<li>Bug fix: incorrect VDBE code was being generated for the following
    circumstance: a query on an indexed table containing a WHERE clause with
    an IN operator that had a subquery on its right-hand side.</li>
}

chng {2000 Aug 18 (Version 1.0.1)} {
<li>Fix a bug in the configure script.</li>
<li>Minor revisions to the website.</li>
}

chng {2000 Aug 17 (Version 1.0)} {
<li>Change the <b>sqlite</b> program so that it can read
    databases for which it lacks write permission.  (It used to
    refuse all access if it could not write.)</li>
}

chng {2000 Aug 9} {
<li>Treat carriage returns as white space.</li>
}

chng {2000 Aug 8} {
<li>Added pattern matching to the ".table" command in the "sqlite"
command shell.</li>
}

chng {2000 Aug 4} {
<li>Documentation updates</li>
<li>Added "busy" and "timeout" methods to the Tcl interface</li>
}

chng {2000 Aug 3} {
<li>File format version number was being stored in sqlite_master.tcl
    multiple times. This was harmless, but unnecessary. It is now fixed.</li>
}

chng {2000 Aug 2} {
<li>The file format for indices was changed slightly in order to work
    around an inefficiency that can sometimes come up with GDBM when
    there are large indices having many entries with the same key.
    <font color="red">** Incompatible Change **</font></li>
}

chng {2000 Aug 1} {
<li>The parser's stack was overflowing on a very long UPDATE statement.
    This is now fixed.</li>
}

chng {2000 July 31} {
<li>Finish the <a href="vdbe.html">VDBE tutorial</a>.</li>
<li>Added documentation on compiling to WindowsNT.</li>
<li>Fix a configuration program for WindowsNT.</li>
<li>Fix a configuration problem for HPUX.</li>
}

chng {2000 July 29} {
<li>Better labels on column names of the result.</li>
}

chng {2000 July 28} {
<li>Added the <b>sqlite_busy_handler()</b> 
    and <b>sqlite_busy_timeout()</b> interface.</li>
}

chng {2000 June 23} {
<li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li>
}

chng {2000 June 21} {
<li>Clean up comments and variable names.  Changes to documentation.
    No functional changes to the code.</li>
}

chng {2000 June 19} {
<li>Column names in UPDATE statements were case sensitive.
    This mistake has now been fixed.</li>
}

chng {2000 June 16} {
<li>Added the concatenate string operator (||)</li>
}

chng {2000 June 12} {
<li>Added the fcnt() function to the SQL interpreter.  The fcnt() function
    returns the number of database "Fetch" operations that have occurred.
    This function is designed for use in test scripts to verify that
    queries are efficient and appropriately optimized.  Fcnt() has no other
    useful purpose, as far as I know.</li>
<li>Added a bunch more tests that take advantage of the new fcnt() function.
    The new tests did not uncover any new problems.</li>
}

chng {2000 June 8} {
<li>Added lots of new test cases</li>
<li>Fix a few bugs discovered while adding test cases</li>
<li>Begin adding lots of new documentation</li>
}

chng {2000 June 6} {
<li>Added compound select operators: <B>UNION</b>, <b>UNION ALL</B>,
<b>INTERSECT</b>, and <b>EXCEPT</b></li>
<li>Added support for using <b>(SELECT ...)</b> within expressions</li>
<li>Added support for <b>IN</b> and <b>BETWEEN</b> operators</li>
<li>Added support for <b>GROUP BY</b> and <b>HAVING</b></li>
<li>NULL values are now reported to the callback as a NULL pointer
    rather than an empty string.</li>
}

chng {2000 June 3} {
<li>Added support for default values on columns of a table.</li>
<li>Improved test coverage.  Fixed a few obscure bugs found by the
improved tests.</li>
}

chng {2000 June 2} {
<li>All database files to be modified by an UPDATE, INSERT or DELETE are 
now locked before any changes are made to any files.  
This makes it safe (I think) to access
the same database simultaneously from multiple processes.</li>
<li>The code appears stable so we are now calling it "beta".</li>
}

chng {2000 June 1} {
<li>Better support for file locking so that two or more processes 
(or threads)
can access the same database simultaneously.  More work needed in
this area, though.</li>
}

chng {2000 May 31} {
<li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>)
to the SELECT statement.</li>
<li>Added support for <B>SELECT DISTINCT ...</B></li>
}

chng {2000 May 30} {
<li>Added the <b>LIKE</b> operator.</li>
<li>Added a <b>GLOB</b> operator: similar to <B>LIKE</B> 
but it uses Unix shell globbing wildcards instead of the '%' 
and '_' wildcards of SQL.</li>
<li>Added the <B>COPY</b> command patterned after 
<a href="http://www.postgresql.org/">PostgreSQL</a> so that SQLite
can now read the output of the <b>pg_dump</b> database dump utility
of PostgreSQL.</li>
<li>Added a <B>VACUUM</B> command that that calls the 
<b>gdbm_reorganize()</b> function on the underlying database
files.</li>
<li>And many, many bug fixes...</li>
}

chng {2000 May 29} {
<li>Initial Public Release of Alpha code</li>
}

puts {
</DL>
}
footer {$Id:}

# This file contains TCL procedures used to generate standard parts of
# web pages.
#

proc header {txt} {
  puts "<html><head><title>$txt</title></head>"
  puts {<DIV class="pdf_ignore">}
  puts \
{<body bgcolor="white" link="#50695f" vlink="#508896">
<table width="100%" border="0">
<tr><td valign="top">
<a href="index.html"><img src="sqlite.gif" border="none"></a></td>
<td width="100%"></td>
<td valign="bottom">
<ul>
<li><a href="http://www.sqlite.org/cvstrac/tktnew">bugs</a></li>
<li><a href="changes.html">changes</a></li>
<li><a href="contrib">contrib</a></li>
<li><a href="download.html#cvs">cvs&nbsp;repository</a></li>
<li><a href="docs.html">documentation</a></li>
</ul>
</td>
<td width="10"></td>
<td valign="bottom">
<ul>
<li><a href="download.html">download</a></li>
<li><a href="faq.html">faq</a></li>
<li><a href="index.html">home</a></li>
<li><a href="copyright.html">license</a></li>
<li><a href="index.html">news</a></li>
</ul>
</td>
<td width="10"></td>
<td valign="bottom">
<ul>
<li><a href="quickstart.html">quick&nbsp;start</a></li>
<li><a href="support.html">support</a></li>
<li><a href="lang.html">syntax</a></li>
<li><a href="http://www.sqlite.org/cvstrac/timeline">timeline</a></li>
<li><a href="http://www.sqlite.org/cvstrac/wiki">wiki</a></li>
</ul>
</td>
</tr></table>
<table width="100%">
<tr><td bgcolor="#80a796"></td></tr>
</table>}
  puts </DIV>
}

proc footer {{rcsid {}}} {
  puts {
<table width="100%">
<tr><td bgcolor="#80a796"></td></tr>
</table>}
  set date [lrange $rcsid 3 4]
  if {$date!=""} {
    puts "<small><i>This page last modified on $date</i></small>"
  }
  puts {</body></html>}
}


# The following proc is used to ensure consistent formatting in the 
# HTML generated by lang.tcl and pragma.tcl.
#
proc Syntax {args} {
  puts {<table cellpadding="10" class=pdf_syntax>}
  foreach {rule body} $args {
    puts "<tr><td align=\"right\" valign=\"top\">"
    puts "<i><font color=\"#ff3434\">$rule</font></i>&nbsp;::=</td>"
    regsub -all < $body {%LT} body
    regsub -all > $body {%GT} body
    regsub -all %LT $body {</font></b><i><font color="#ff3434">} body
    regsub -all %GT $body {</font></i><b><font color="#2c2cf0">} body
    regsub -all {[]|[*?]} $body {</font></b>&<b><font color="#2c2cf0">} body
    regsub -all "\n" [string trim $body] "<br>\n" body
    regsub -all "\n  *" $body "\n\\&nbsp;\\&nbsp;\\&nbsp;\\&nbsp;" body
    regsub -all {[|,.*()]} $body {<big>&</big>} body
    regsub -all { = } $body { <big>=</big> } body
    regsub -all {STAR} $body {<big>*</big>} body
    ## These metacharacters must be handled to undo being
    ## treated as SQL punctuation characters above.
    regsub -all {RPPLUS} $body {</font></b>)+<b><font color="#2c2cf0">} body
    regsub -all {LP} $body {</font></b>(<b><font color="#2c2cf0">} body
    regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body
    ## Place the left-hand side of the rule in the 2nd table column.
    puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>"
  }
  puts {</table>}
}

#
# Run this Tcl script to generate the compile.html file.
#
set rcsid {$Id: compile.tcl,v 1.5 2005/03/19 15:10:45 drh Exp $ }
source common.tcl
header {Compilation Options For SQLite}

puts {
<h1>Compilation Options For SQLite</h1>

<p>
For most purposes, SQLite can be built just fine using the default
compilation options. However, if required, the compile-time options
documented below can be used to 
<a href="#omitfeatures">omit SQLite features</a> (resulting in
a smaller compiled library size) or to change the
<a href="#defaults">default values</a> of some parameters.
</p>
<p>
Every effort has been made to ensure that the various combinations
of compilation options work harmoniously and produce a working library.
Nevertheless, it is strongly recommended that the SQLite test-suite
be executed to check for errors before using an SQLite library built
with non-standard compilation options.
</p>
<a name="defaults"></a>
<h2>Options To Set Default Parameter Values</h2>

<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i>&lt;1 or 0&gt;</i></b><br>
This macro determines if SQLite creates databases with the 
<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a> 
flag set by default. The default value is 0 (do not create auto-vacuum
databases). In any case the compile-time default may be overridden by the 
"PRAGMA auto_vacuum" command.
</p>

<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
This macro sets the default size of the page-cache for each attached
database, in pages. This can be overridden by the "PRAGMA cache_size"
comamnd. The default value is 2000.
</p>

<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
This macro is used to set the default page-size used when a
database is created. The value assigned must be a power of 2. The
default value is 1024. The compile-time default may be overridden at 
runtime by the "PRAGMA page_size" command.
</p>

<p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
This macro sets the default size of the page-cache for temporary files
created by SQLite to store intermediate results, in pages. It does
not affect the page-cache for the temp database, where tables created
using "CREATE TEMP TABLE" are stored. The default value is 500.
</p>

<p><b>SQLITE_MAX_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
This is used to set the maximum allowable page-size that can
be specified by the "PRAGMA page_size" command. The default value
is 8192.
</p>

<a name="omitfeatures"></a>
<h2>Options To Omit Features</h2>

<p>The following options are used to reduce the size of the compiled
library by omiting optional features. This is probably only useful
in embedded systems where space is especially tight, as even with all
features included the SQLite library is relatively small. Don't forget
to tell your compiler to optimize for binary size! (the -Os option if
using GCC).</p>

<p>The macros in this section do not require values. The following 
compilation switches all have the same effect:<br>
-DSQLITE_OMIT_ALTERTABLE<br>
-DSQLITE_OMIT_ALTERTABLE=1<br>
-DSQLITE_OMIT_ALTERTABLE=0
</p>

<p>If any of these options are defined, then the same set of SQLITE_OMIT_XXX
options must also be defined when using the 'lemon' tool to generate a parse.c
file. Because of this, these options may only used when the library is built
from source, not from the collection of pre-packaged C files provided for
non-UNIX like platforms on the website.
</p>

<p><b>SQLITE_OMIT_ALTERTABLE</b><br>
When this option is defined, the 
<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the 
library. Executing an ALTER TABLE statement causes a parse error.
</p>

<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
Defining this option omits the authorization callback feature from the
library. The <a href="capi3ref.html#sqlite3_set_authorizer">
sqlite3_set_authorizer()</a> API function is not present in the library.
</p>

<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
If this option is defined, the library cannot create or write to 
databases that support 
<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a
"PRAGMA auto_vacuum" statement is not an error, but does not return a value
or modify the auto-vacuum flag in the database file. If a database that
supports auto-vacuum is opened by a library compiled with this option, it
is automatically opened in read-only mode.
</p>

<p><b>SQLITE_OMIT_AUTOINCREMENT</b><br>
This option is used to omit the AUTOINCREMENT functionality. When this 
is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT"
behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a 
NULL is inserted. The sqlite_sequence system table is neither created, nor
respected if it already exists.
</p>
<p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p>

<p><b>SQLITE_OMIT_BLOB_LITERAL</b><br>
When this option is defined, it is not possible to specify a blob in
an SQL statement using the X'ABCD' syntax.</p> 
}
#<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases
#that contain blobs, so disabling this functionality may render a database
#unvacuumable.
#</p>
#<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>
puts {

<p><b>SQLITE_OMIT_COMPLETE</b><br>
This option causes the <a href="capi3ref.html#sqlite3_complete">
sqlite3_complete</a> API to be omitted.
</p>

<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
This option is used to omit the compound SELECT functionality. 
<a href="lang_select.html">SELECT statements</a> that use the 
UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will 
cause a parse error.
</p>

<p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br>
In the future, this option will be used to omit the 
<a href="lang_conflict.html">ON CONFLICT</a> clause from the library.
</p>

<p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br>
If this option is defined, SQLite's built-in date and time manipulation
functions are omitted. Specifically, the SQL functions julianday(), date(),
time(), datetime() and strftime() are not available. The default column
values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available.
</p>

<p><b>SQLITE_OMIT_EXPLAIN</b><br>
Defining this option causes the EXPLAIN command to be omitted from the
library. Attempting to execute an EXPLAIN statement will cause a parse
error.
</p>

<p><b>SQLITE_OMIT_FLOATING_POINT</b><br>
This option is used to omit floating-point number support from the SQLite
library. When specified, specifying a floating point number as a literal 
(i.e. "1.01") results in a parse error.
</p>
<p>In the future, this option may also disable other floating point 
functionality, for example the sqlite3_result_double(), 
sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double() 
API functions.
</p>

<p><b>SQLITE_OMIT_FOREIGN_KEY</b><br>
If this option is defined, FOREIGN KEY clauses in column declarations are
ignored.
</p>

<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br>
This option may be used to omit the 
<a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a> 
command from the compiled library.
</p>

<p><b>SQLITE_OMIT_MEMORYDB</b><br>
When this is defined, the library does not respect the special database
name ":memory:" (normally used to create an in-memory database). If 
":memory:" is passed to sqlite3_open(), a file with this name will be 
opened or created.
</p>

<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br>
Defining this option omits pragmas related to the pager subsystem from 
the build. Currently, the 
<a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and 
<a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted.
</p>

<p><b>SQLITE_OMIT_PRAGMA</b><br>
This option is used to omit the <a href="pragma.html">PRAGMA command</a> 
from the library. Note that it is useful to define the macros that omit
specific pragmas in addition to this, as they may also remove supporting code
in other sub-systems. This macro removes the PRAGMA command only.
</p>

<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
This option may be defined to omit the capability to issue "progress" 
callbacks during long-running SQL statements. The 
<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
API function is not present in the library.

<p><b>SQLITE_OMIT_REINDEX</b><br>
When this option is defined, the <a href="lang_reindex.html">REINDEX</a> 
command is not included in the library. Executing a REINDEX statement causes 
a parse error.
</p>

<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br>
Defining this option omits pragmas for querying the database schema from 
the build. Currently, the 
<a href="pragma.html#pragma_table_info">table_info</a>,
<a href="pragma.html#pragma_index_info">index_info</a>,
<a href="pragma.html#pragma_index_list">index_list</a> and
<a href="pragma.html#pragma_database_list">database_list</a>
pragmas are omitted.
</p>

<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br>
Defining this option omits pragmas for querying and modifying the 
database schema version and user version from the build. Specifically, the 
<a href="pragma.html#pragma_schema_version">schema_version</a> and
<a href="pragma.html#pragma_user_version">user_version</a>
pragmas are omitted.

<p><b>SQLITE_OMIT_SUBQUERY</b><br>
<p>If defined, support for sub-selects and the IN() operator are omitted.
</p>

<p><b>SQLITE_OMIT_TCL_VARIABLE</b><br>
<p>If this macro is defined, then the special "$<variable-name>" syntax
used to automatically bind SQL variables to TCL variables is omitted.
</p>

<p><b>SQLITE_OMIT_TRIGGER</b><br>
Defining this option omits support for VIEW objects. Neither the 
<a href="lang_createtrigger.html">CREATE TRIGGER</a> or 
<a href="lang_droptrigger.html">DROP TRIGGER</a> 
commands are available in this case, attempting to execute either will result
in a parse error.
</p>
<p>
WARNING: If this macro is defined, it will not be possible to open a database
for which the schema contains TRIGGER objects. 
</p>

<p><b>SQLITE_OMIT_UTF16</b><br>
This macro is used to omit support for UTF16 text encoding. When this is
defined all API functions that return or accept UTF16 encoded text are
unavailable. These functions can be identified by the fact that they end
with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and
sqlite3_bind_text16().
</p>

<p><b>SQLITE_OMIT_VACUUM</b><br>
When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> 
command is not included in the library. Executing a VACUUM statement causes 
a parse error.
</p>

<p><b>SQLITE_OMIT_VIEW</b><br>
Defining this option omits support for VIEW objects. Neither the 
<a href="lang_createview.html">CREATE VIEW</a> or 
<a href="lang_dropview.html">DROP VIEW</a> 
commands are available in this case, attempting to execute either will result
in a parse error.
</p>
<p>
WARNING: If this macro is defined, it will not be possible to open a database
for which the schema contains VIEW objects. 
</p>
}
footer $rcsid

#
# Run this Tcl script to generate the constraint.html file.
#
set rcsid {$Id: conflict.tcl,v 1.4 2004/10/10 17:24:55 drh Exp $ }
source common.tcl
header {Constraint Conflict Resolution in SQLite}
puts {
<h1>Constraint Conflict Resolution in SQLite</h1>

<p>
In most SQL databases, if you have a UNIQUE constraint on
a table and you try to do an UPDATE or INSERT that violates
the constraint, the database will abort the operation in
progress, back out any prior changes associated with
UPDATE or INSERT command, and return an error.
This is the default behavior of SQLite.
Beginning with version 2.3.0, though, SQLite allows you to
define alternative ways for dealing with constraint violations.
This article describes those alternatives and how to use them.
</p>

<h2>Conflict Resolution Algorithms</h2>

<p>
SQLite defines five constraint conflict resolution algorithms
as follows:
</p>

<dl>
<dt><b>ROLLBACK</b></dt>
<dd><p>When a constraint violation occurs, an immediate ROLLBACK
occurs, thus ending the current transaction, and the command aborts
with a return code of SQLITE_CONSTRAINT.  If no transaction is
active (other than the implied transaction that is created on every
command) then this algorithm works the same as ABORT.</p></dd>

<dt><b>ABORT</b></dt>
<dd><p>When a constraint violation occurs, the command backs out
any prior changes it might have made and aborts with a return code
of SQLITE_CONSTRAINT.  But no ROLLBACK is executed so changes
from prior commands within the same transaction
are preserved.  This is the default behavior for SQLite.</p></dd>

<dt><b>FAIL</b></dt>
<dd><p>When a constraint violation occurs, the command aborts with a
return code SQLITE_CONSTRAINT.  But any changes to the database that
the command made prior to encountering the constraint violation
are preserved and are not backed out.  For example, if an UPDATE
statement encountered a constraint violation on the 100th row that
it attempts to update, then the first 99 row changes are preserved
by change to rows 100 and beyond never occur.</p></dd>

<dt><b>IGNORE</b></dt>
<dd><p>When a constraint violation occurs, the one row that contains
the constraint violation is not inserted or changed.  But the command
continues executing normally.  Other rows before and after the row that
contained the constraint violation continue to be inserted or updated
normally.  No error is returned.</p></dd>

<dt><b>REPLACE</b></dt>
<dd><p>When a UNIQUE constraint violation occurs, the pre-existing row
that caused the constraint violation is removed prior to inserting
or updating the current row.  Thus the insert or update always occurs.
The command continues executing normally.  No error is returned.</p></dd>
</dl>

<h2>Why So Many Choices?</h2>

<p>SQLite provides multiple conflict resolution algorithms for a
couple of reasons.  First, SQLite tries to be roughly compatible with as
many other SQL databases as possible, but different SQL database
engines exhibit different conflict resolution strategies.  For
example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and
MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE.
By supporting all five alternatives, SQLite provides maximum
portability.</p>

<p>Another reason for supporting multiple algorithms is that sometimes
it is useful to use an algorithm other than the default.
Suppose, for example, you are
inserting 1000 records into a database, all within a single
transaction, but one of those records is malformed and causes
a constraint error.  Under PostgreSQL or Oracle, none of the
1000 records would get inserted.  In MySQL, some subset of the
records that appeared before the malformed record would be inserted
but the rest would not.  Neither behavior is especially helpful.
What you really want is to use the IGNORE algorithm to insert
all but the malformed record.</p>

}
footer $rcsid

<html>
<body bgcolor="white">
<h1 align="center">
Copyright Release for<br>
Contributions To SQLite
</h1>

<p>
SQLite is software that implements an embeddable SQL database engine.
SQLite is available for free download from http://www.sqlite.org/.
The principal author and maintainer of SQLite has disclaimed all
copyright interest in his contributions to SQLite
and thus released his contributions into the public domain.
In order to keep the SQLite software unencumbered by copyright
claims, the principal author asks others who may from time to
time contribute changes and enhancements to likewise disclaim
their own individual copyright interest.
</p>

<p>
Because the SQLite software found at http://www.sqlite.org/ is in the
public domain, anyone is free to download the SQLite software
from that website, make changes to the software, use, distribute,
or sell the modified software, under either the original name or
under some new name, without any need to obtain permission, pay
royalties, acknowledge the original source of the software, or
in any other way compensate, identify, or notify the original authors.  
Nobody is in any way compelled to contribute their SQLite changes and 
enhancements back to the SQLite website.  This document concerns
only changes and enhancements to SQLite that are intentionally and
deliberately contributed back to the SQLite website.  
</p>

<p>
For the purposes of this document, "SQLite software" shall mean any
computer source code, documentation, makefiles, test scripts, or
other information that is published on the SQLite website, 
http://www.sqlite.org/.  Precompiled binaries are excluded from
the definition of "SQLite software" in this document because the
process of compiling the software may introduce information from
outside sources which is not properly a part of SQLite.
</p>

<p>
The header comments on the SQLite source files exhort the reader to
share freely and to never take more than one gives.
In the spirit of that exhortation I make the following declarations:
</p>

<ol>
<li><p>
I dedicate to the public domain 
any and all copyright interest in the SQLite software that
was publicly available on the SQLite website (http://www.sqlite.org/) prior
to the date of the signature below and any changes or enhancements to
the SQLite software 
that I may cause to be published on that website in the future.
I make this dedication for the benefit of the public at large and
to the detriment of my heirs and successors.  I intend this
dedication to be an overt act of relinquishment in perpetuity of
all present and future rights to the SQLite software under copyright
law.
</p></li>

<li><p>
To the best of my knowledge and belief, the changes and enhancements that
I have contributed to SQLite are either originally written by me
or are derived from prior works which I have verified are also
in the public domain and are not subject to claims of copyright
by other parties.
</p></li>

<li><p>
To the best of my knowledge and belief, no individual, business, organization,
government, or other entity has any copyright interest
in the SQLite software as it existed on the
SQLite website as of the date on the signature line below.
</p></li>

<li><p>
I agree never to publish any additional information
to the SQLite website (by CVS, email, scp, FTP, or any other means) unless
that information is an original work of authorship by me or is derived from 
prior published versions of SQLite.
I agree never to copy and paste code into the SQLite code base from
other sources.
I agree never to publish on the SQLite website any information that
would violate a law or breach a contract.
</p></li>
</ol>

<p>
<table width="100%" cellpadding="0" cellspacing="0">
<tr>
<td width="60%" valign="top">
Signature:
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
</td><td valign="top" align="left">
Date:
</td></tr>
<td colspan=2>
Name (printed):
</td>
</tr>
</table>
</body>
</html>

set rcsid {$Id: copyright.tcl,v 1.7 2007/05/06 21:20:43 drh Exp $}
source common.tcl
header {SQLite Copyright}
puts {
<h2>SQLite Copyright</h2>

<table align="right" vspace="0" hspace="10" border="1" cellpadding="20">
<tr><td align="center">
<img src="nocopy.gif"><br>
SQLite is in the<br>
<a href="http://en.wikipedia.org/wiki/Public_Domain">Public Domain</a>
</td></tr>
</table>

<p>
All of the deliverable code in SQLite has been dedicated to the
<a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a>
by the authors.
All code authors, and representatives of the companies they work for,
have signed affidavits dedicating their contributions to
the public domain and originals of
those signed affidavits are stored in a firesafe at the main offices
of <a href="http://www.hwaci.com">Hwaci</a>.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute
the original SQLite code, either in source code form or as a compiled binary,
for any purpose, commercial or non-commercial, and by any means.
</p>

<p>
The previous paragraph applies to the deliverable code in SQLite - 
those parts of the SQLite library that you actually bundle and
ship with a larger application.  Portions of the documentation and
some code used as part of the build process might fall under
other licenses.  The details here are unclear.  We do not worry
about the licensing of the documentation and build code so much
because none of these things are part of the core deliverable
SQLite library.
</p>

<p>
All of the deliverable code in SQLite has been written from scratch.
No code has been taken from other projects or from the open
internet.  Every line of code can be traced back to its original
author, and all of those authors have public domain dedications
on file.  So the SQLite code base is clean and is
uncontaminated with licensed code from other projects.
</p>

<h2>Obtaining An Explicit License To Use SQLite</h2>

<p>
Even though SQLite is in the public domain and does not require
a license, some users want to obtain a license anyway.  Some reasons
for obtaining a license include:
</p>

<ul>
<li> You are using SQLite in a jurisdiction that does not recognize
     the public domain.  </li>
<li> You are using SQLite in a jurisdiction that does not recognize
     the right of an author to dedicate their work to the public
     domain. </li>
<li> You want to hold a tangible legal document
     as evidence that you have the legal right to use and distribute
     SQLite. </li>
<li> Your legal department tells you that you have to purchase a license.
     </li>
</ul>

<p>
If you feel like you really have to purchase a license for SQLite,
<a href="http://www.hwaci.com/">Hwaci</a>, the company that employs 
the architect and principal developers of SQLite, will sell you
one.
Please contact:
</p>

<blockquote>
D. Richard Hipp <br />
Hwaci - Applied Software Research <br />
704.948.4565 <br />
<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
</blockquote>

<h2>Contributed Code</h2>

<p>
In order to keep SQLite completely free and unencumbered by copyright,
all new contributors to the SQLite code base are asked to dedicate
their contributions to the public domain.
If you want to send a patch or enhancement for possible inclusion in the
SQLite source tree, please accompany the patch with the following statement:
</p>

<blockquote><i>
The author or authors of this code dedicate any and all copyright interest
in this code to the public domain.  We make this dedication for the benefit
of the public at large and to the detriment of our heirs and successors.
We intend this dedication to be an overt act of relinquishment in
perpetuity of all present and future rights to this code under copyright law.
</i></blockquote>

<p>
We are not able to accept patches or changes to 
SQLite that are not accompanied by a statement such as the above.
In addition, if you make
changes or enhancements as an employee, then a simple statement such as the
above is insufficient.  You must also send by surface mail a copyright release
signed by a company officer.
A signed original of the copyright release should be mailed to:</p>

<blockquote>
Hwaci<br>
6200 Maple Cove Lane<br>
Charlotte, NC 28269<br>
USA
</blockquote>

<p>
A template copyright release is available
in <a href="copyright-release.pdf">PDF</a> or
<a href="copyright-release.html">HTML</a>.
You can use this release to make future changes. 
</p>
}
footer $rcsid

set rcsid {$Id: datatype3.tcl,v 1.17 2007/06/20 16:13:23 drh Exp $}
source common.tcl
header {Datatypes In SQLite Version 3}
puts {
<h2>Datatypes In SQLite Version 3</h2>

<h3>1. Storage Classes</h3>

<P>Version 2 of SQLite stores all column values as ASCII text.
Version 3 enhances this by providing the ability to store integer and
real numbers in a more compact format and the capability to store
BLOB data.</P>

<P>Each value stored in an SQLite database (or manipulated by the
database engine) has one of the following storage classes:</P>
<UL>
	<LI><P><B>NULL</B>. The value is a NULL value.</P>
	<LI><P><B>INTEGER</B>. The value is a signed integer, stored in 1,
	2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.</P>
	<LI><P><B>REAL</B>. The value is a floating point value, stored as
	an 8-byte IEEE floating point number.</P>
	<LI><P><B>TEXT</B>. The value is a text string, stored using the
	database encoding (UTF-8, UTF-16BE or UTF-16-LE).</P>
	<LI><P><B>BLOB</B>. The value is a blob of data, stored exactly as
	it was input.</P>
</UL>

<P>As in SQLite version 2, any column in a version 3 database except an INTEGER
PRIMARY KEY may be used to store any type of value. The exception to
this rule is described below under 'Strict Affinity Mode'.</P>

<P>All values supplied to SQLite, whether as literals embedded in SQL
statements or values bound to pre-compiled SQL statements
are assigned a storage class before the SQL statement is executed.
Under circumstances described below, the
database engine may convert values between numeric storage classes
(INTEGER and REAL) and TEXT during query execution. 
</P>

<P>Storage classes are initially assigned as follows:</P>
<UL>
	<LI><P>Values specified as literals as part of SQL statements are
	assigned storage class TEXT if they are enclosed by single or double
	quotes, INTEGER if the literal is specified as an unquoted number
	with no decimal point or exponent, REAL if the literal is an
	unquoted number with a decimal point or exponent and NULL if the
	value is a NULL. Literals with storage class BLOB are specified
        using the X'ABCD' notation.</P>
	<LI><P>Values supplied using the sqlite3_bind_* APIs are assigned
	the storage class that most closely matches the native type bound
	(i.e. sqlite3_bind_blob() binds a value with storage class BLOB).</P>
</UL>
<P>The storage class of a value that is the result of an SQL scalar
operator depends on the outermost operator of the expression.
User-defined functions may return values with any storage class. It
is not generally possible to determine the storage class of the
result of an expression at compile time.</P>

<a name="affinity">
<h3>2. Column Affinity</h3>

<p>
In SQLite version 3, the type of a value is associated with the value
itself, not with the column or variable in which the value is stored.
(This is sometimes called
<a href="http://www.cliki.net/manifest%20type%20system">
manifest typing</a>.)
All other SQL databases engines that we are aware of use the more
restrictive system of static typing where the type is associated with
the container, not the value.
</p>

<p>
In order to maximize compatibility between SQLite and other database
engines, SQLite support the concept of "type affinity" on columns.
The type affinity of a column is the recommended type for data stored
in that column.  The key here is that the type is recommended, not
required.  Any column can still store any type of data, in theory.
It is just that some columns, given the choice, will prefer to use
one storage class over another.  The preferred storage class for
a column is called its "affinity".
</p>

<P>Each column in an SQLite 3 database is assigned one of the
following type affinities:</P>
<UL>
	<LI>TEXT</LI>
	<LI>NUMERIC</LI>
	<LI>INTEGER</LI>
        <LI>REAL</li>
	<LI>NONE</LI>
</UL>

<P>A column with TEXT affinity stores all data using storage classes
NULL, TEXT or BLOB. If numerical data is inserted into a column with
TEXT affinity it is converted to text form before being stored.</P>

<P>A column with NUMERIC affinity may contain values using all five
storage classes. When text data is inserted into a NUMERIC column, an
attempt is made to convert it to an integer or real number before it
is stored. If the conversion is successful, then the value is stored
using the INTEGER or REAL storage class. If the conversion cannot be
performed the value is stored using the TEXT storage class. No
attempt is made to convert NULL or blob values.</P>

<P>A column that uses INTEGER affinity behaves in the same way as a
column with NUMERIC affinity, except that if a real value with no
floating point component (or text value that converts to such) is
inserted it is converted to an integer and stored using the INTEGER
storage class.</P>

<P>A column with REAL affinity behaves like a column with NUMERIC
affinity except that it forces integer values into floating point
representation.  (As an optimization, integer values are stored on
disk as integers in order to take up less space and are only converted
to floating point as the value is read out of the table.)</P>

<P>A column with affinity NONE does not prefer one storage class over
another.  It makes no attempt to coerce data before
it is inserted.</P>

<h4>2.1 Determination Of Column Affinity</h4>

<P>The type affinity of a column is determined by the declared type
of the column, according to the following rules:</P>
<OL>
	<LI><P>If the datatype contains the string &quot;INT&quot; then it
	is assigned INTEGER affinity.</P>

	<LI><P>If the datatype of the column contains any of the strings
	&quot;CHAR&quot;, &quot;CLOB&quot;, or &quot;TEXT&quot; then that
	column has TEXT affinity. Notice that the type VARCHAR contains the
	string &quot;CHAR&quot; and is thus assigned TEXT affinity.</P>

	<LI><P>If the datatype for a column
         contains the string &quot;BLOB&quot; or if
        no datatype is specified then the column has affinity NONE.</P>

        <LI><P>If the datatype for a column
        contains any of the strings &quot;REAL&quot;, &quot;FLOA&quot;,
        or &quot;DOUB&quot; then the column has REAL affinity</P>

	<LI><P>Otherwise, the affinity is NUMERIC.</P>
</OL>

<P>If a table is created using a "CREATE TABLE &lt;table&gt; AS
SELECT..." statement, then all columns have no datatype specified
and they are given no affinity.</P>

<h4>2.2 Column Affinity Example</h4>

<blockquote>
<PRE>CREATE TABLE t1(
    t  TEXT,
    nu NUMERIC, 
    i  INTEGER,
    no BLOB
);

-- Storage classes for the following row:
-- TEXT, REAL, INTEGER, TEXT
INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0');

-- Storage classes for the following row:
-- TEXT, REAL, INTEGER, REAL
INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0);
</PRE>
</blockquote>

<a name="comparisons">
<h3>3. Comparison Expressions</h3>

<P>Like SQLite version 2, version 3
features the binary comparison operators '=',
'&lt;', '&lt;=', '&gt;=' and '!=', an operation to test for set
membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P>
<P>The results of a comparison depend on the storage classes of the
two values being compared, according to the following rules:</P>
<UL>
	<LI><P>A value with storage class NULL is considered less than any
	other value (including another value with storage class NULL).</P>

	<LI><P>An INTEGER or REAL value is less than any TEXT or BLOB value.
	When an INTEGER or REAL is compared to another INTEGER or REAL, a
	numerical comparison is performed.</P>

	<LI><P>A TEXT value is less than a BLOB value. When two TEXT values
	are compared, the C library function memcmp() is usually used to
	determine the result. However this can be overridden, as described
	under 'User-defined collation Sequences' below.</P>

	<LI><P>When two BLOB values are compared, the result is always
	determined using memcmp().</P>
</UL>

<P>SQLite may attempt to convert values between the numeric storage
classes (INTEGER and REAL) and TEXT before performing a comparison.
For binary comparisons, this is done in the cases enumerated below.
The term "expression" used in the bullet points below means any
SQL scalar expression or literal other than a column value.  Note that
if X and Y.Z are a column names, then +X and +Y.Z are considered
expressions.</P>
<UL>
	<LI><P>When a column value is compared to the result of an
	expression, the affinity of the column is applied to the result of
	the expression before the comparison takes place.</P>

	<LI><P>When two column values are compared, if one column has
	INTEGER or REAL or NUMERIC affinity and the other does not, 
        then NUMERIC affinity is applied to any values with storage
        class TEXT extracted from the non-NUMERIC column.</P>

	<LI><P>When the results of two expressions are compared, no
        conversions occur.  The results are compared as is.  If a string
        is compared to a number, the number will always be less than the
        string.</P>
</UL>

<P>
In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a &gt;= b
AND a &lt;= c", even if this means that different affinities are applied to
'a' in each of the comparisons required to evaluate the expression.
</P>

<P>Expressions of the type "a IN (SELECT b ....)" are handled by the three
rules enumerated above for binary comparisons (e.g. in a
similar manner to "a = b"). For example if 'b' is a column value
and 'a' is an expression, then the affinity of 'b' is applied to 'a'
before any comparisons take place.</P>

<P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR
a = +y OR a = +z".  The values to the right of the IN operator (the "x", "y",
and "z" values in this example) are considered to be expressions, even if they
happen to be column values.  If the value of the left of the IN operator is
a column, then the affinity of that column is used.  If the value is an
expression then no conversions occur.
</P>

<h4>3.1 Comparison Example</h4>

<blockquote>
<PRE>
CREATE TABLE t1(
    a TEXT,
    b NUMERIC,
    c BLOB
);

-- Storage classes for the following row:
-- TEXT, REAL, TEXT
INSERT INTO t1 VALUES('500', '500', '500');

-- 60 and 40 are converted to '60' and '40' and values are compared as TEXT.
SELECT a &lt; 60, a &lt; 40 FROM t1;
1|0

-- Comparisons are numeric. No conversions are required.
SELECT b &lt; 60, b &lt; 600 FROM t1;
0|1

-- Both 60 and 600 (storage class NUMERIC) are less than '500'
-- (storage class TEXT).
SELECT c &lt; 60, c &lt; 600 FROM t1;
0|0
</PRE>
</blockquote>
<h3>4. Operators</h3>

<P>All mathematical operators (which is to say, all operators other
than the concatenation operator &quot;||&quot;) apply NUMERIC
affinity to all operands prior to being carried out. If one or both
operands cannot be converted to NUMERIC then the result of the
operation is NULL.</P>

<P>For the concatenation operator, TEXT affinity is applied to both
operands. If either operand cannot be converted to TEXT (because it
is NULL or a BLOB) then the result of the concatenation is NULL.</P>

<h3>5. Sorting, Grouping and Compound SELECTs</h3>

<P>When values are sorted by an ORDER by clause, values with storage
class NULL come first, followed by INTEGER and REAL values
interspersed in numeric order, followed by TEXT values usually in
memcmp() order, and finally BLOB values in memcmp() order. No storage
class conversions occur before the sort.</P>

<P>When grouping values with the GROUP BY clause values with
different storage classes are considered distinct, except for INTEGER
and REAL values which are considered equal if they are numerically
equal. No affinities are applied to any values as the result of a
GROUP by clause.</P>

<P>The compound SELECT operators UNION,
INTERSECT and EXCEPT perform implicit comparisons between values.
Before these comparisons are performed an affinity may be applied to
each value. The same affinity, if any, is applied to all values that
may be returned in a single column of the compound SELECT result set.
The affinity applied is the affinity of the column returned by the
left most component SELECTs that has a column value (and not some
other kind of expression) in that position. If for a given compound
SELECT column none of the component SELECTs return a column value, no
affinity is applied to the values from that column before they are
compared.</P>

<h3>6. Other Affinity Modes</h3>

<P>The above sections describe the operation of the database engine
in 'normal' affinity mode. SQLite version 3 will feature two other affinity
modes, as follows:</P>
<UL>
	<LI><P><B>Strict affinity</B> mode. In this mode if a conversion
	between storage classes is ever required, the database engine
	returns an error and the current statement is rolled back.</P>

	<LI><P><B>No affinity</B> mode. In this mode no conversions between
	storage classes are ever performed. Comparisons between values of
	different storage classes (except for INTEGER and REAL) are always
	false.</P>
</UL>

<a name="collation"></a>
<h3>7. User-defined Collation Sequences</h3>

<p>
By default, when SQLite compares two text values, the result of the
comparison is determined using memcmp(), regardless of the encoding of the
string. SQLite v3 provides the ability for users to supply arbitrary
comparison functions, known as user-defined collation sequences, to be used
instead of memcmp().
</p>  
<p>
Aside from the default collation sequence BINARY, implemented using
memcmp(), SQLite features one extra built-in collation sequences 
intended for testing purposes, the NOCASE collation:
</p>  
<UL>
	<LI><b>BINARY</b> - Compares string data using memcmp(), regardless
                            of text encoding.</LI>
	<LI><b>NOCASE</b> - The same as binary, except the 26 upper case
			    characters used by the English language are
			    folded to their lower case equivalents before
                            the comparison is performed.  </UL>


<h4>7.1 Assigning Collation Sequences from SQL</h4>

<p>
Each column of each table has a default collation type. If a collation type
other than BINARY is required, a COLLATE clause is specified as part of the
<a href="lang_createtable.html">column definition</a> to define it. 
</p>  

<p>
Whenever two text values are compared by SQLite, a collation sequence is
used to determine the results of the comparison according to the following
rules. Sections 3 and 5 of this document describe the circumstances under
which such a comparison takes place.
</p>  

<p>
For binary comparison operators (=, <, >, <= and >=) if either operand is a
column, then the default collation type of the column determines the
collation sequence to use for the comparison. If both operands are columns,
then the collation type for the left operand determines the collation
sequence used. If neither operand is a column, then the BINARY collation
sequence is used.  For the purposes of this paragraph, a column name
preceded by one or more unary "+" operators is considered a column name.
</p>  

<p>
The expression "x BETWEEN y and z" is equivalent to "x &gt;= y AND x &lt;=
z". The expression "x IN (SELECT y ...)" is handled in the same way as the
expression "x = y" for the purposes of determining the collation sequence
to use. The collation sequence used for expressions of the form "x IN (y, z
...)" is the default collation type of x if x is a column, or BINARY
otherwise.
</p>  

<p>
An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT
statement may be assigned a collation sequence to be used for the sort
operation explicitly. In this case the explicit collation sequence is
always used.  Otherwise, if the expression sorted by an ORDER BY clause is
a column, then the default collation type of the column is used to
determine sort order. If the expression is not a column, then the BINARY
collation sequence is used.
</p>  

<h4>7.2 Collation Sequences Example</h4>
<p>
The examples below identify the collation sequences that would be used to
determine the results of text comparisons that may be performed by various
SQL statements. Note that a text comparison may not be required, and no
collation sequence used, in the case of numeric, blob or NULL values.
</p>
<blockquote>
<PRE>
CREATE TABLE t1(
    a,                 -- default collation type BINARY
    b COLLATE BINARY,  -- default collation type BINARY
    c COLLATE REVERSE, -- default collation type REVERSE
    d COLLATE NOCASE   -- default collation type NOCASE
);

-- Text comparison is performed using the BINARY collation sequence.
SELECT (a = b) FROM t1;

-- Text comparison is performed using the NOCASE collation sequence.
SELECT (d = a) FROM t1;

-- Text comparison is performed using the BINARY collation sequence.
SELECT (a = d) FROM t1;

-- Text comparison is performed using the REVERSE collation sequence.
SELECT ('abc' = c) FROM t1;

-- Text comparison is performed using the REVERSE collation sequence.
SELECT (c = 'abc') FROM t1;

-- Grouping is performed using the NOCASE collation sequence (i.e. values
-- 'abc' and 'ABC' are placed in the same group).
SELECT count(*) GROUP BY d FROM t1;

-- Grouping is performed using the BINARY collation sequence.
SELECT count(*) GROUP BY (d || '') FROM t1;

-- Sorting is performed using the REVERSE collation sequence.
SELECT * FROM t1 ORDER BY c;

-- Sorting is performed using the BINARY collation sequence.
SELECT * FROM t1 ORDER BY (c || '');

-- Sorting is performed using the NOCASE collation sequence.
SELECT * FROM t1 ORDER BY c COLLATE NOCASE;

</PRE>
</blockquote>

}
footer $rcsid

#
# Run this script to generated a datatypes.html output file
#
set rcsid {$Id: datatypes.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
source common.tcl
header {Datatypes In SQLite version 2}
puts {
<h2>Datatypes In SQLite Version 2</h2>

<h3>1.0 &nbsp; Typelessness</h3>
<p>
SQLite is "typeless".  This means that you can store any
kind of data you want in any column of any table, regardless of the
declared datatype of that column.  
(See the one exception to this rule in section 2.0 below.)
This behavior is a feature, not
a bug.  A database is suppose to store and retrieve data and it 
should not matter to the database what format that data is in.
The strong typing system found in most other SQL engines and
codified in the SQL language spec is a misfeature -
it is an example of the implementation showing through into the
interface.  SQLite seeks to overcome this misfeature by allowing
you to store any kind of data into any kind of column and by
allowing flexibility in the specification of datatypes.
</p>

<p>
A datatype to SQLite is any sequence of zero or more names
optionally followed by a parenthesized lists of one or two
signed integers.  Notice in particular that a datatype may
be <em>zero</em> or more names.  That means that an empty
string is a valid datatype as far as SQLite is concerned.
So you can declare tables where the datatype of each column
is left unspecified, like this:
</p>

<blockquote><pre>
CREATE TABLE ex1(a,b,c);
</pre></blockquote>

<p>
Even though SQLite allows the datatype to be omitted, it is
still a good idea to include it in your CREATE TABLE statements,
since the data type often serves as a good hint to other
programmers about what you intend to put in the column. And
if you ever port your code to another database engine, that
other engine will probably require a datatype of some kind.
SQLite accepts all the usual datatypes.  For example:
</p>

<blockquote><pre>
CREATE TABLE ex2(
  a VARCHAR(10),
  b NVARCHAR(15),
  c TEXT,
  d INTEGER,
  e FLOAT,
  f BOOLEAN,
  g CLOB,
  h BLOB,
  i TIMESTAMP,
  j NUMERIC(10,5)
  k VARYING CHARACTER (24),
  l NATIONAL VARYING CHARACTER(16)
);
</pre></blockquote>

<p>
And so forth.  Basically any sequence of names optionally followed by 
one or two signed integers in parentheses will do.
</p>

<h3>2.0 &nbsp; The INTEGER PRIMARY KEY</h3>

<p>
One exception to the typelessness of SQLite is a column whose type
is INTEGER PRIMARY KEY.  (And you must use "INTEGER" not "INT".
A column of type INT PRIMARY KEY is typeless just like any other.)
INTEGER PRIMARY KEY columns must contain a 32-bit signed integer.  Any
attempt to insert non-integer data will result in an error.
</p>

<p>
INTEGER PRIMARY KEY columns can be used to implement the equivalent
of AUTOINCREMENT.  If you try to insert a NULL into an INTEGER PRIMARY
KEY column, the column will actually be filled with a integer that is
one greater than the largest key already in the table.  Or if the
largest key is 2147483647, then the column will be filled with a
random integer.  Either way, the INTEGER PRIMARY KEY column will be
assigned a unique integer.  You can retrieve this integer using
the <b>sqlite_last_insert_rowid()</b> API function or using the
<b>last_insert_rowid()</b> SQL function in a subsequent SELECT statement.
</p>

<h3>3.0 &nbsp; Comparison and Sort Order</h3>

<p>
SQLite is typeless for the purpose of deciding what data is allowed
to be stored in a column.  But some notion of type comes into play
when sorting and comparing data.  For these purposes, a column or
an expression can be one of two types: <b>numeric</b> and <b>text</b>.
The sort or comparison may give different results depending on which
type of data is being sorted or compared.
</p>

<p>
If data is of type <b>text</b> then the comparison is determined by
the standard C data comparison functions <b>memcmp()</b> or
<b>strcmp()</b>.  The comparison looks at bytes from two inputs one
by one and returns the first non-zero difference.
Strings are '\000' terminated so shorter
strings sort before longer strings, as you would expect.
</p>

<p>
For numeric data, this situation is more complex.  If both inputs
look like well-formed numbers, then they are converted
into floating point values using <b>atof()</b> and compared numerically.
If one input is not a well-formed number but the other is, then the
number is considered to be less than the non-number.  If neither inputs
is a well-formed number, then <b>strcmp()</b> is used to do the
comparison.
</p>

<p>
Do not be confused by the fact that a column might have a "numeric"
datatype.  This does not mean that the column can contain only numbers.
It merely means that if the column does contain a number, that number
will sort in numerical order.
</p>

<p>
For both text and numeric values, NULL sorts before any other value.
A comparison of any value against NULL using operators like "&lt;" or
"&gt;=" is always false.
</p>

<h3>4.0 &nbsp; How SQLite Determines Datatypes</h3>

<p>
For SQLite version 2.6.3 and earlier, all values used the numeric datatype.
The text datatype appears in version 2.7.0 and later.  In the sequel it
is assumed that you are using version 2.7.0 or later of SQLite.
</p>

<p>
For an expression, the datatype of the result is often determined by
the outermost operator.  For example, arithmetic operators ("+", "*", "%")
always return a numeric results.  The string concatenation operator
("||") returns a text result.  And so forth.  If you are ever in doubt
about the datatype of an expression you can use the special <b>typeof()</b>
SQL function to determine what the datatype is.  For example:
</p>

<blockquote><pre>
sqlite&gt; SELECT typeof('abc'+123);
numeric
sqlite&gt; SELECT typeof('abc'||123);
text
</pre></blockquote>

<p>
For table columns, the datatype is determined by the type declaration
of the CREATE TABLE statement.  The datatype is text if and only if
the type declaration contains one or more of the following strings:
</p>

<blockquote>
BLOB<br>
CHAR<br>
CLOB</br>
TEXT
</blockquote>

<p>
The search for these strings in the type declaration is case insensitive,
of course.  If any of the above strings occur anywhere in the type
declaration, then the datatype of the column is text.  Notice that
the type "VARCHAR" contains "CHAR" as a substring so it is considered
text.</p>

<p>If none of the strings above occur anywhere in the type declaration,
then the datatype is numeric.  Note in particular that the datatype for columns
with an empty type declaration is numeric.
</p>

<h3>5.0 &nbsp; Examples</h3>

<p>
Consider the following two command sequences:
</p>

<blockquote><pre>
CREATE TABLE t1(a INTEGER UNIQUE);        CREATE TABLE t2(b TEXT UNIQUE);
INSERT INTO t1 VALUES('0');               INSERT INTO t2 VALUES(0);
INSERT INTO t1 VALUES('0.0');             INSERT INTO t2 VALUES(0.0);
</pre></blockquote>

<p>In the sequence on the left, the second insert will fail.  In this case,
the strings '0' and '0.0' are treated as numbers since they are being 
inserted into a numeric column but 0==0.0 which violates the uniqueness
constraint.  However, the second insert in the right-hand sequence works.  In
this case, the constants 0 and 0.0 are treated a strings which means that
they are distinct.</p>

<p>SQLite always converts numbers into double-precision (64-bit) floats
for comparison purposes.  This means that a long sequence of digits that
differ only in insignificant digits will compare equal if they
are in a numeric column but will compare unequal if they are in a text
column.  We have:</p>

<blockquote><pre>
INSERT INTO t1                            INSERT INTO t2
   VALUES('12345678901234567890');           VALUES(12345678901234567890);
INSERT INTO t1                            INSERT INTO t2
   VALUES('12345678901234567891');           VALUES(12345678901234567891);
</pre></blockquote>

<p>As before, the second insert on the left will fail because the comparison
will convert both strings into floating-point number first and the only
difference in the strings is in the 20-th digit which exceeds the resolution
of a 64-bit float.  In contrast, the second insert on the right will work
because in that case, the numbers being inserted are strings and are
compared using memcmp().</p>

<p>
Numeric and text types make a difference for the DISTINCT keyword too:
</p>

<blockquote><pre>
CREATE TABLE t3(a INTEGER);               CREATE TABLE t4(b TEXT);
INSERT INTO t3 VALUES('0');               INSERT INTO t4 VALUES(0);
INSERT INTO t3 VALUES('0.0');             INSERT INTO t4 VALUES(0.0);
SELECT DISTINCT * FROM t3;                SELECT DISTINCT * FROM t4;
</pre></blockquote>

<p>
The SELECT statement on the left returns a single row since '0' and '0.0'
are treated as numbers and are therefore indistinct.  But the SELECT 
statement on the right returns two rows since 0 and 0.0 are treated
a strings which are different.</p>
}
footer $rcsid

set rcsid {$Id: different.tcl,v 1.8 2006/12/18 14:12:21 drh Exp $}
source common.tcl
header {Distinctive Features Of SQLite}
puts {
<p>
This page highlights some of the characteristics of SQLite that are
unusual and which make SQLite different from many other SQL
database engines.
</p>
}
proc feature {tag name text} {
  puts "<a name=\"$tag\" />"
  puts "<p><b>$name</b></p>\n"
  puts "<blockquote>$text</blockquote>\n"
}

feature zeroconfig {Zero-Configuration} {
  SQLite does not need to be "installed" before it is used. 
  There is no "setup" procedure.  There is no
  server process that needs to be started, stopped, or configured.
  There is
  no need for an administrator to create a new database instance or assign
  access permissions to users.
  SQLite uses no configuration files.
  Nothing needs to be done to tell the system that SQLite is running.
  No actions are required to recover after a system crash or power failure.
  There is nothing to troubleshoot.
  <p>
  SQLite just works.
  <p>
  Other more familiar database engines run great once you get them going.
  But doing the initial installation and configuration can be
  intimidatingly complex.
}

feature serverless {Serverless} {
  Most SQL database engines are implemented as a separate server
  process.  Programs that want to access the database communicate
  with the server using some kind of interprocess communcation
  (typically TCP/IP) to send requests to the server and to receive
  back results.  SQLite does not work this way.  With SQLite, the
  process that wants to access the database reads and writes
  directly from the database files on disk.  There is no intermediary
  server process.
  <p>
  There are advantages and disadvantages to being serverless.  The
  main advantage is that there is no separate server process
  to install, setup, configure, initialize, manage, and troubleshoot.
  This is one reason why SQLite is a "zero-configuration" database
  engine.  Programs that use SQLite require no administrative support
  for setting up the database engine before they are run.  Any program
  that is able to access the disk is able to use an SQLite database.
  <p>
  On the other hand, a database engine that uses a server can provide
  better protection from bugs in the client application - stray pointers
  in a client cannot corrupt memory on the server.  And because a server
  is a single persistent process, it is able control database access with
  more precision, allowing for finer grain locking and better concurrancy.
  <p>
  Most SQL database engines are client/server based.  Of those that are
  serverless, SQLite is the only one that this author knows of that
  allows multiple applications to access the same database at the same time.
}

feature onefile {Single Database File} {
  An SQLite database is a single ordinary disk file that can be located
  anywhere in the directory hierarchy.  If SQLite can read
  the disk file then it can read anything in the database.  If the disk
  file and its directory are writable, then SQLite can change anything
  in the database.   Database files can easily be copied onto a USB
  memory stick or emailed for sharing.
  <p>
  Other SQL database engines tend to store data as a large collection of
  files.  Often these files are in a standard location that only the
  database engine itself can access.  This makes the data more secure,
  but also makes it harder to access.  Some SQL database engines provide
  the option of writing directly to disk and bypassing the filesystem
  all together.  This provides added performance, but at the cost of
  considerable setup and maintenance complexity.
}

feature small {Compact} {
  When optimized for size, the whole SQLite library with everything enabled
  is less than 225KiB in size (as measured on an ix86 using the "size"
  utility from the GNU compiler suite.)  Unneeded features can be disabled
  at compile-time to further reduce the size of the library to under
  170KiB if desired.
  <p>
  Most other SQL database engines are much larger than this.  IBM boasts
  that it's recently released CloudScape database engine is "only" a 2MiB
  jar file - 10 times larger than SQLite even after it is compressed!
  Firebird boasts that it's client-side library is only 350KiB.  That's
  50% larger than SQLite and does not even contain the database engine.
  The Berkeley DB library from Sleepycat is 450KiB and it omits SQL
  support, providing the programmer with only simple key/value pairs.
}

feature typing {Manifest typing} {
  Most SQL database engines use static typing.  A datatype is associated
  with each column in a table and only values of that particular datatype
  are allowed to be stored in that column.  SQLite relaxes this restriction
  by using manifest typing.
  In manifest typing, the datatype is a property of the value itself, not 
  of the column in which the value is stored.
  SQLite thus allows the user to store
  any value of any datatype into any column regardless of the declared type
  of that column.  (There are some exceptions to this rule: An INTEGER
  PRIMARY KEY column may only store integers.  And SQLite attempts to coerce
  values into the declared datatype of the column when it can.)
  <p>
  As far as we can tell, the SQL language specification allows the use
  of manifest typing.   Nevertheless, most other SQL database engines are
  statically typed and so some people
  feel that the use of manifest typing is a bug in SQLite.  But the authors
  of SQLite feel very strongly that this is a feature.  The use of manifest
  typing in SQLite is a deliberate design decision which has proven in practice
  to make SQLite more reliable and easier to use, especially when used in
  combination with dynamically typed programming languages such as Tcl and
  Python.
}

feature flex {Variable-length records} {
  Most other SQL database engines allocated a fixed amount of disk space
  for each row in most tables.  They play special tricks for handling
  BLOBs and CLOBs which can be of wildly varying length.  But for most
  tables, if you declare a column to be a VARCHAR(100) then the database
  engine will allocate
  100 bytes of disk space regardless of how much information you actually
  store in that column.
  <p>
  SQLite, in contrast, use only the amount of disk space actually
  needed to store the information in a row.  If you store a single
  character in a VARCHAR(100) column, then only a single byte of disk
  space is consumed.  (Actually two bytes - there is some overhead at
  the beginning of each column to record its datatype and length.)
  <p>
  The use of variable-length records by SQLite has a number of advantages.
  It results in smaller database files, obviously.  It also makes the
  database run faster, since there is less information to move to and from
  disk.  And, the use of variable-length records makes it possible for
  SQLite to employ manifest typing instead of static typing.
}

feature readable {Readable source code} {
  The source code to SQLite is designed to be readable and accessible to
  the average programmer.  All procedures and data structures and many
  automatic variables are carefully commented with useful information about
  what they do.  Boilerplate commenting is omitted.
}

feature vdbe {SQL statements compile into virtual machine code} {
  Every SQL database engine compiles each SQL statement into some kind of
  internal data structure which is then used to carry out the work of the
  statement.  But in most SQL engines that internal data structure is a
  complex web of interlinked structures and objects.  In SQLite, the compiled
  form of statements is a short program in a machine-language like
  representation.  Users of the database can view this 
  <a href="opcode.html">virtual machine language</a>
  by prepending the <a href="lang_explain.html">EXPLAIN</a> keyword
  to a query.
  <p>
  The use of a virtual machine in SQLite has been a great benefit to
  library's development.  The virtual machine provides a crisp, well-defined
  junction between the front-end of SQLite (the part that parses SQL
  statements and generates virtual machine code) and the back-end (the
  part that executes the virtual machine code and computes a result.)
  The virtual machine allows the developers to see clearly and in an
  easily readable form what SQLite is trying to do with each statement
  it compiles, which is a tremendous help in debugging.
  Depending on how it is compiled, SQLite also has the capability of
  tracing the execution of the virtual machine - printing each
  virtual machine instruction and its result as it executes.
}

#feature binding {Tight bindings to dynamic languages} {
#  Because it is embedded, SQLite can have a much tighter and more natural
#  binding to high-level dynamic languages such as Tcl, Perl, Python,
#  PHP, and Ruby.
#  For example, 
#}

feature license {Public domain} {
  The source code for SQLite is in the public domain.  No claim of copyright
  is made on any part of the core source code.  (The documentation and test
  code is a different matter - some sections of documentation and test logic
  are governed by open-sources licenses.)  All contributors to the
  SQLite core software have signed affidavits specifically disavowing any
  copyright interest in the code.  This means that anybody is able to legally
  do anything they want with the SQLite source code.
  <p>
  There are other SQL database engines with liberal licenses that allow
  the code to be broadly and freely used.  But those other engines are
  still governed by copyright law.  SQLite is different in that copyright
  law simply does not apply.  
  <p>
  The source code files for other SQL database engines typically begin
  with a comment describing your license rights to view and copy that file.
  The SQLite source code contains no license since it is not governed by
  copyright.  Instead of a license, the SQLite source code offers a blessing:
  <blockquote>
  <i>May you do good and not evil<br>
  May you find forgiveness for yourself and forgive others<br>
  May you share freely, never taking more than you give.</i>
  </blockquote>
}

feature extensions {SQL language extensions} {
  SQLite provides a number of enhancements to the SQL language 
  not normally found in other database engines.
  The EXPLAIN keyword and manifest typing have already been mentioned
  above.  SQLite also provides statements such as 
  <a href="lang_replace.html">REPLACE</a> and the
  <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for
  added control over the resolution of constraint conflicts.
  SQLite supports <a href="lang_attach.html">ATTACH</a> and
  <a href="lang_detach.html">DETACH</a> commands that allow multiple
  independent databases to be used together in the same query.
  And SQLite defines APIs that allows the user to add new
  <a href="capi3ref.html#sqlite3_create_function">SQL functions</a>
  and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>.
}


footer $rcsid

# This script generates the "docs.html" page that describes various
# sources of documentation available for SQLite.
#
set rcsid {$Id: docs.tcl,v 1.15 2007/10/04 00:29:29 drh Exp $}
source common.tcl
header {SQLite Documentation}
puts {
<h2>Available Documentation</h2>
<table width="100%" cellpadding="5">
}

proc doc {name url desc} {
  puts {<tr><td valign="top" align="right">}
  regsub -all { +} $name {\&nbsp;} name
  puts "<a href=\"$url\">$name</a></td>"
  puts {<td width="10"></td>}
  puts {<td valign="top" align="left">}
  puts $desc
  puts {</td></tr>}
}

doc {Appropriate Uses For SQLite} {whentouse.html} {
  This document describes situations where SQLite is an approriate
  database engine to use versus situations where a client/server
  database engine might be a better choice.
}

doc {Distinctive Features} {different.html} {
  This document enumerates and describes some of the features of
  SQLite that make it different from other SQL database engines.
}

doc {SQLite In 5 Minutes Or Less} {quickstart.html} {
  A very quick introduction to programming with SQLite.
}

doc {SQL Syntax} {lang.html} {
  This document describes the SQL language that is understood by
  SQLite.  
}
doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} {
  This document describes each API function separately.
}
doc {Sharing Cache Mode} {sharedcache.html} {
  Version 3.3.0 and later supports the ability for two or more
  database connections to share the same page and schema cache.
  This feature is useful for certain specialized applications.
}
doc {Tcl API} {tclsqlite.html} {
  A description of the TCL interface bindings for SQLite.
}

doc {How SQLite Implements Atomic Commit} {ac/atomiccommit.html} {
  A description of the logic within SQLite that implements
  transactions with atomic commit, even in the face of power
  failures.
}
doc {Moving From SQLite 3.4 to 3.5} {34to35.html} {
  A document describing the differences between SQLite version 3.4.2
  and 3.5.0.
}

doc {Pragma commands} {pragma.html} {
  This document describes SQLite performance tuning options and other 
  special purpose database commands.
}
doc {SQLite Version 3} {version3.html} {
  A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
}
doc {Version 3 C/C++ API} {capi3.html} {
  A description of the C/C++ interface bindings for SQLite version 3.0.0
  and following.
}
doc {Version 3 DataTypes } {datatype3.html} {
  SQLite version 3 introduces the concept of manifest typing, where the
  type of a value is associated with the value itself, not the column that
  it is stored in.
  This page describes data typing for SQLite version 3 in further detail.
}

doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
  A description of how the new locking code in version 3 increases
  concurrancy and decreases the problem of writer starvation.
}

doc {Overview Of The Optimizer} {optoverview.html} {
  A quick overview of the various query optimizations that are
  attempted by the SQLite code generator.
}


doc {Null Handling} {nulls.html} {
  Different SQL database engines handle NULLs in different ways.  The
  SQL standards are ambiguous.  This document describes how SQLite handles
  NULLs in comparison with other SQL database engines.
}

doc {Copyright} {copyright.html} {
  SQLite is in the public domain.  This document describes what that means
  and the implications for contributors.
}

doc {Unsupported SQL} {omitted.html} {
  This page describes features of SQL that SQLite does not support.
}

doc {Version 2 C/C++ API} {c_interface.html} {
  A description of the C/C++ interface bindings for SQLite through version 
  2.8
}


doc {Version 2 DataTypes } {datatypes.html} {
  A description of how SQLite version 2 handles SQL datatypes.
  Short summary:  Everything is a string.
}

doc {Release History} {changes.html} {
  A chronology of SQLite releases going back to version 1.0.0
}


doc {Speed Comparison} {speed.html} {
  The speed of version 2.7.6 of SQLite is compared against PostgreSQL and
  MySQL.
}

doc {Architecture} {arch.html} {
  An architectural overview of the SQLite library, useful for those who want
  to hack the code.
}

doc {VDBE Tutorial} {vdbe.html} {
  The VDBE is the subsystem within SQLite that does the actual work of
  executing SQL statements.  This page describes the principles of operation
  for the VDBE in SQLite version 2.7.  This is essential reading for anyone
  who want to modify the SQLite sources.
}

doc {VDBE Opcodes} {opcode.html} {
  This document is an automatically generated description of the various
  opcodes that the VDBE understands.  Programmers can use this document as
  a reference to better understand the output of EXPLAIN listings from
  SQLite.
}

doc {Compilation Options} {compile.html} {
  This document describes the compile time options that may be set to 
  modify the default behaviour of the library or omit optional features
  in order to reduce binary size.
}

doc {Backwards Compatibility} {formatchng.html} {
  This document details all of the incompatible changes to the SQLite
  file format that have occurred since version 1.0.0.
}

puts {</table>}
footer $rcsid

#
# Run this TCL script to generate HTML for the download.html file.
#
set rcsid {$Id: download.tcl,v 1.27 2007/05/08 18:30:36 drh Exp $}
source common.tcl
header {SQLite Download Page}

puts {
<h2>SQLite Download Page</h1>
<table width="100%" cellpadding="5">
}

proc Product {pattern desc} {
  regsub {V[23]} $pattern {*} p3
  regsub V2 $pattern {(2[0-9a-z._]+)} pattern
  regsub V3 $pattern {(3[0-9a-z._]+)} pattern
  set p2 [string map {* .*} $pattern]
  set flist [glob -nocomplain $p3]
  foreach file [lsort -dict $flist] {
    if {![regexp ^$p2\$ $file all version]} continue
    regsub -all _ $version . version
    set size [file size $file]
    set units bytes
    if {$size>1024*1024} {
      set size [format %.2f [expr {$size/(1024.0*1024.0)}]]
      set units MiB
    } elseif {$size>1024} {
      set size [format %.2f [expr {$size/(1024.0)}]]
      set units KiB
    }
    puts "<tr><td width=\"10\"></td>"
    puts "<td valign=\"top\" align=\"right\">"
    puts "<a href=\"$file\">$file</a><br>($size $units)</td>"
    puts "<td width=\"5\"></td>"
    regsub -all VERSION $desc $version d2
    puts "<td valign=\"top\">[string trim $d2]</td></tr>"
  }
}
cd doc

proc Heading {title} {
  puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>"
}

Heading {Precompiled Binaries for Linux}

Product sqlite3-V3.bin.gz {
  A command-line program for accessing and modifying
  SQLite version 3.* databases.
  See <a href="sqlite.html">the documentation</a> for additional information.
}

Product sqlite-V3.bin.gz {
  A command-line program for accessing and modifying
  SQLite databases.
  See <a href="sqlite.html">the documentation</a> for additional information.
}

Product tclsqlite-V3.so.gz {
  Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
  You can import this shared library into either
  tclsh or wish to get SQLite database access from Tcl/Tk.
  See <a href="tclsqlite.html">the documentation</a> for details.
}

Product sqlite-V3.so.gz {
  A precompiled shared-library for Linux without the TCL bindings.
}

Product fts1-V3.so.gz {
  A precompiled 
  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> 
  for Linux.
}

Product fts2-V3.so.gz {
  A precompiled 
  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> 
  for Linux.
}

Product sqlite-devel-V3.i386.rpm {
  RPM containing documentation, header files, and static library for
  SQLite version VERSION.
}
Product sqlite-V3-1.i386.rpm {
  RPM containing shared libraries and the <b>sqlite</b> command-line
  program for SQLite version VERSION.
}

Product sqlite*_analyzer-V3.bin.gz {
  An analysis program for database files compatible with SQLite 
  version VERSION and later.
}

Heading {Precompiled Binaries For Windows}

Product sqlite-V3.zip {
  A command-line program for accessing and modifing SQLite databases.
  See <a href="sqlite.html">the documentation</a> for additional information.
}
Product tclsqlite-V3.zip {
  Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
  You can import this shared library into either
  tclsh or wish to get SQLite database access from Tcl/Tk.
  See <a href="tclsqlite.html">the documentation</a> for details.
}
Product sqlitedll-V3.zip {
  This is a DLL of the SQLite library without the TCL bindings.
  The only external dependency is MSVCRT.DLL.
}

Product fts1dll-V3.zip {
  A precompiled 
  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> 
  for win32.
}

Product fts2dll-V3.zip {
  A precompiled 
  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> 
  for win32.
}

Product sqlite*_analyzer-V3.zip {
  An analysis program for database files compatible with SQLite version
  VERSION and later.
}


Heading {Source Code}

Product {sqlite-V3.tar.gz} {
  A tarball of the complete source tree for SQLite version VERSION
  including all of the documentation.
}

Product {sqlite-source-V3.zip} {
  This ZIP archive contains preprocessed C code for the SQLite library as
  individual source files.
  Unlike the tarballs below, all of the preprocessing and automatic
  code generation has already been done on these C code files, so they
  can be converted to object code directly with any ordinary C compiler.
}

Product {sqlite-amalgamation-V3.zip} {
  This ZIP archive contains all preprocessed C code combined into a
  single source file (the
  <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
  amalgamation</a>).
}

Product {sqlite-V3-tea.tar.gz} {
  A tarball of proprocessed source code together with a
  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>
  compatible configure script and makefile.
}

Product {sqlite-V3.src.rpm} {
  An RPM containing complete source code for SQLite version VERSION
}

Heading {Cross-Platform Binaries}

Product {sqlite-V3.kit} {
  A <a href="http://www.equi4.com/starkit.html">starkit</a> containing
  precompiled SQLite binaries and Tcl bindings for Linux-x86, Windows,
  and Mac OS-X ppc and x86.
}

Heading {Historical Binaries And Source Code}

Product sqlite-V2.bin.gz {
  A command-line program for accessing and modifying
  SQLite version 2.* databases on Linux-x86.
}
Product sqlite-V2.zip {
  A command-line program for accessing and modifying 
  SQLite version 2.* databases on win32.
}

Product sqlite*_analyzer-V2.bin.gz {
  An analysis program for version 2.* database files on Linux-x86
}
Product sqlite*_analyzer-V2.zip {
  An analysis program for version 2.* database files on win32.
}
Product {sqlite-source-V2.zip} {
  This ZIP archive contains C source code for the SQLite library
  version VERSION.
}




puts {
</table>

<a name="cvs">
<h3>Direct Access To The Sources Via Anonymous CVS</h3>

<p>
All SQLite source code is maintained in a 
<a href="http://www.cvshome.org/">CVS</a> repository that is
available for read-only access by anyone.  You can 
interactively view the
repository contents and download individual files
by visiting
<a href="http://www.sqlite.org/cvstrac/dir?d=sqlite">
http://www.sqlite.org/cvstrac/dir?d=sqlite</a>.
To access the repository directly, use the following
commands:
</p>

<blockquote><pre>
cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login
cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite
</pre></blockquote>

<p>
When the first command prompts you for a password, enter "anonymous".
</p>

<p>
To access the SQLite version 2.8 sources, begin by getting the 3.0
tree as described above.  Then update to the "version_2" branch
as follows:
</p>

<blockquote><pre>
cvs update -r version_2
</pre></blockquote>

}

footer $rcsid

#
# Run this Tcl script to generate the dynload.html file.
#
set rcsid {$Id: dynload.tcl,v 1.1 2001/02/11 16:58:22 drh Exp $}

puts {<html>
<head>
  <title>How to build a dynamically loaded Tcl extension for SQLite</title>
</head>
<body bgcolor=white>
<h1 align=center>
How To Build A Dynamically Loaded Tcl Extension
</h1>}
puts {<p>
<i>This note was contributed by 
<a href="bsaunder@tampabay.rr.com.nospam">Bill Saunders</a>.  Thanks, Bill!</i>

<p>
To compile the SQLite Tcl extension into a dynamically loaded module 
I did the following:
</p>

<ol>
<li><p>Do a standard compile
(I had a dir called bld at the same level as sqlite  ie
        /root/bld
        /root/sqlite
I followed the directions and did a standard build in the bld
directory)</p></li>

<li><p>
Now do the following in the bld directory
<blockquote><pre>
gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so
</pre></blockquote></p></li>

<li><p>
This should produce the file sqlite.so in the bld directory</p></li>

<li><p>
Create a pkgIndex.tcl file that contains this line

<blockquote><pre>
package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]]
</pre></blockquote></p></li>

<li><p>
To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li>

<li><p>
From that directory start wish</p></li>

<li><p>
Execute the following tcl command (tells tcl where to fine loadable
modules)
<blockquote><pre>
lappend auto_path [exec pwd]
</pre></blockquote></p></li>

<li><p>
Load the package 
<blockquote><pre>
package require sqlite
</pre></blockquote></p></li>

<li><p>
Have fun....</p></li>
</ul>

</body></html>}

#
# Run this script to generated a faq.html output file
#
set rcsid {$Id: faq.tcl,v 1.40 2007/09/04 01:58:27 drh Exp $}
source common.tcl
header {SQLite Frequently Asked Questions</title>}

set cnt 1
proc faq {question answer} {
  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
  incr ::cnt
}

#############
# Enter questions and answers here.

faq {
  How do I create an AUTOINCREMENT field.
} {
  <p>Short answer: A column declared INTEGER PRIMARY KEY will
  autoincrement.</p>

  <p>Here is the long answer:
  If you declare a column of a table to be INTEGER PRIMARY KEY, then
  whenever you insert a NULL
  into that column of the table, the NULL is automatically converted
  into an integer which is one greater than the largest value of that
  column over all other rows in the table, or 1 if the table is empty.
  (If the largest possible integer key, 9223372036854775807, then an
  unused key value is chosen at random.)
  For example, suppose you have a table like this:
<blockquote><pre>
CREATE TABLE t1(
  a INTEGER PRIMARY KEY,
  b INTEGER
);
</pre></blockquote>
  <p>With this table, the statement</p>
<blockquote><pre>
INSERT INTO t1 VALUES(NULL,123);
</pre></blockquote>
  <p>is logically equivalent to saying:</p>
<blockquote><pre>
INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);
</pre></blockquote>

  <p>There is a new API function named
  <a href="capi3ref.html#sqlite3_last_insert_rowid">
  sqlite3_last_insert_rowid()</a> which will return the integer key
  for the most recent insert operation.</p>

  <p>Note that the integer key is one greater than the largest
  key that was in the table just prior to the insert.  The new key
  will be unique over all keys currently in the table, but it might
  overlap with keys that have been previously deleted from the
  table.  To create keys that are unique over the lifetime of the
  table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY
  declaration.  Then the key chosen will be one more than than the
  largest key that has ever existed in that table.  If the largest
  possible key has previously existed in that table, then the INSERT
  will fail with an SQLITE_FULL error code.</p>
}

faq {
  What datatypes does SQLite support?
} {
  <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p>
}

faq {
  SQLite lets me insert a string into a database column of type integer!
} {
  <p>This is a feature, not a bug.  SQLite does not enforce data type
  constraints.  Any data can be
  inserted into any column.  You can put arbitrary length strings into
  integer columns, floating point numbers in boolean columns, or dates
  in character columns.  The datatype you assign to a column in the
  CREATE TABLE command does not restrict what data can be put into
  that column.  Every column is able to hold
  an arbitrary length string.  (There is one exception: Columns of
  type INTEGER PRIMARY KEY may only hold a 64-bit signed integer.
  An error will result
  if you try to put anything other than an integer into an
  INTEGER PRIMARY KEY column.)</p>

  <p>But SQLite does use the declared type of a column as a hint
  that you prefer values in that format.  So, for example, if a
  column is of type INTEGER and you try to insert a string into
  that column, SQLite will attempt to convert the string into an
  integer.  If it can, it inserts the integer instead.  If not,
  it inserts the string.  This feature is sometimes
  call <a href="datatype3.html#affinity">type or column affinity</a>.
  </p>
}

faq {
  Why doesn't SQLite allow me to use '0' and '0.0' as the primary
  key on two different rows of the same table?
} {
  <p>Your primary key must have a numeric type.  Change the datatype of
  your primary key to TEXT and it should work.</p>

  <p>Every row must have a unique primary key.  For a column with a
  numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
  same value because they compare equal to one another numerically.
  (See the previous question.)  Hence the values are not unique.</p>
}
        

faq {
  Can multiple applications or multiple instances of the same
  application access a single database file at the same time?
} {
  <p>Multiple processes can have the same database open at the same
  time.  Multiple processes can be doing a SELECT
  at the same time.  But only one process can be making changes to
  the database at any moment in time, however.</p>

  <p>SQLite uses reader/writer locks to control access to the database.
  (Under Win95/98/ME which lacks support for reader/writer locks, a
  probabilistic simulation is used instead.)
  But use caution: this locking mechanism might
  not work correctly if the database file is kept on an NFS filesystem.
  This is because fcntl() file locking is broken on many NFS implementations.
  You should avoid putting SQLite database files on NFS if multiple
  processes might try to access the file at the same time.  On Windows,
  Microsoft's documentation says that locking may not work under FAT
  filesystems if you are not running the Share.exe daemon.  People who
  have a lot of experience with Windows tell me that file locking of
  network files is very buggy and is not dependable.  If what they
  say is true, sharing an SQLite database between two or more Windows
  machines might cause unexpected problems.</p>

  <p>We are aware of no other <i>embedded</i> SQL database engine that
  supports as much concurrancy as SQLite.  SQLite allows multiple processes
  to have the database file open at once, and for multiple processes to
  read the database at once.  When any process wants to write, it must
  lock the entire database file for the duration of its update.  But that
  normally only takes a few milliseconds.  Other processes just wait on
  the writer to finish then continue about their business.  Other embedded
  SQL database engines typically only allow a single process to connect to
  the database at once.</p>

  <p>However, client/server database engines (such as PostgreSQL, MySQL,
  or Oracle) usually support a higher level of concurrency and allow
  multiple processes to be writing to the same database at the same time.
  This is possible in a client/server database because there is always a
  single well-controlled server process available to coordinate access.
  If your application has a need for a lot of concurrency, then you should
  consider using a client/server database.  But experience suggests that
  most applications need much less concurrency than their designers imagine.
  </p>

  <p>When SQLite tries to access a file that is locked by another
  process, the default behavior is to return SQLITE_BUSY.  You can
  adjust this behavior from C code using the 
  <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
  <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
  API functions.</p>
}

faq {
  Is SQLite threadsafe?
} {
  <p>Yes.  Sometimes.  In order to be thread-safe, SQLite must be compiled
  with the SQLITE_THREADSAFE preprocessor macro set to 1.  Both the windows
  and linux precompiled binaries in the distribution are compiled this way.
  If you are unsure if the SQLite library you are linking against is compiled
  to be threadsafe you can call the
  <a href="capi3ref.html#sqlite3_threadsafe">sqlite3_threadsafe()</a>
  interface to find out.
  </p>

  <p>Prior to version 3.3.1,
  an <b>sqlite3</b> structure could only be used in the same thread
  that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
  to create it.
  You could not open a
  database in one thread then pass the handle off to another thread for
  it to use.  This was due to limitations (bugs?) in many common threading
  implementations such as on RedHat9.  Specifically, an fcntl() lock
  created by one thread cannot be removed or modified by a different
  thread on the troublesome systems.  And since SQLite uses fcntl()
  locks heavily for concurrency control, serious problems arose if you 
  start moving database connections across threads.</p>

  <p>The restriction on moving database connections across threads
  was relaxed somewhat in version 3.3.1.  With that and subsequent
  versions, it is safe to move a connection handle across threads
  as long as the connection is not holding any fcntl() locks.  You
  can safely assume that no locks are being held if no
  transaction is pending and all statements have been finalized.</p>

  <p>Under UNIX, you should not carry an open SQLite database across
  a fork() system call into the child process.  Problems will result
  if you do.</p>
}

faq {
  How do I list all tables/indices contained in an SQLite database
} {
  <p>If you are running the <b>sqlite3</b> command-line access program
  you can type "<b>.tables</b>" to get a list of all tables.  Or you
  can type "<b>.schema</b>" to see the complete database schema including
  all tables and indices.  Either of these commands can be followed by
  a LIKE pattern that will restrict the tables that are displayed.</p>

  <p>From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python
  bindings) you can get access to table and index names by doing a SELECT
  on a special table named "<b>SQLITE_MASTER</b>".  Every SQLite database
  has an SQLITE_MASTER table that defines the schema for the database.
  The SQLITE_MASTER table looks like this:</p>
<blockquote><pre>
CREATE TABLE sqlite_master (
  type TEXT,
  name TEXT,
  tbl_name TEXT,
  rootpage INTEGER,
  sql TEXT
);
</pre></blockquote>
  <p>For tables, the <b>type</b> field will always be <b>'table'</b> and the
  <b>name</b> field will be the name of the table.  So to get a list of
  all tables in the database, use the following SELECT command:</p>
<blockquote><pre>
SELECT name FROM sqlite_master
WHERE type='table'
ORDER BY name;
</pre></blockquote>
  <p>For indices, <b>type</b> is equal to <b>'index'</b>, <b>name</b> is the
  name of the index and <b>tbl_name</b> is the name of the table to which
  the index belongs.  For both tables and indices, the <b>sql</b> field is
  the text of the original CREATE TABLE or CREATE INDEX statement that
  created the table or index.  For automatically created indices (used
  to implement the PRIMARY KEY or UNIQUE constraints) the <b>sql</b> field
  is NULL.</p>

  <p>The SQLITE_MASTER table is read-only.  You cannot change this table
  using UPDATE, INSERT, or DELETE.  The table is automatically updated by
  CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.</p>

  <p>Temporary tables do not appear in the SQLITE_MASTER table.  Temporary
  tables and their indices and triggers occur in another special table
  named SQLITE_TEMP_MASTER.  SQLITE_TEMP_MASTER works just like SQLITE_MASTER
  except that it is only visible to the application that created the 
  temporary tables.  To get a list of all tables, both permanent and
  temporary, one can use a command similar to the following:
<blockquote><pre>
SELECT name FROM 
   (SELECT * FROM sqlite_master UNION ALL
    SELECT * FROM sqlite_temp_master)
WHERE type='table'
ORDER BY name
</pre></blockquote>
}

faq {
  Are there any known size limits to SQLite databases?
} {
  <p>See <a href="limits.html">limits.html</a> for a full discussion of
  the limits of SQLite.</p>
}

faq {
  What is the maximum size of a VARCHAR in SQLite?
} {
  <p>SQLite does not enforce the length of a VARCHAR.  You can declare
  a VARCHAR(10) and SQLite will be happy to let you put 500 characters
  in it.  And it will keep all 500 characters intact - it never truncates.
  </p>
}

faq {
  Does SQLite support a BLOB type?
} {
  <p>SQLite versions 3.0 and later allow you to store BLOB data in any 
  column, even columns that are declared to hold some other type.</p>
}

faq {
  How do I add or delete columns from an existing table in SQLite.
} {
  <p>SQLite has limited 
  <a href="lang_altertable.html">ALTER TABLE</a> support that you can
  use to add a column to the end of a table or to change the name of
  a table.  
  If you what make more complex changes the structure of a table,
  you will have to recreate the
  table.  You can save existing data to a temporary table, drop the
  old table, create the new table, then copy the data back in from
  the temporary table.</p>

  <p>For example, suppose you have a table named "t1" with columns
  names "a", "b", and "c" and that you want to delete column "c" from
  this table.  The following steps illustrate how this could be done:
  </p>

  <blockquote><pre>
BEGIN TRANSACTION;
CREATE TEMPORARY TABLE t1_backup(a,b);
INSERT INTO t1_backup SELECT a,b FROM t1;
DROP TABLE t1;
CREATE TABLE t1(a,b);
INSERT INTO t1 SELECT a,b FROM t1_backup;
DROP TABLE t1_backup;
COMMIT;
</pre></blockquote>
}

faq {
  I deleted a lot of data but the database file did not get any
  smaller.  Is this a bug?
} {
  <p>No.  When you delete information from an SQLite database, the
  unused disk space is added to an internal "free-list" and is reused
  the next time you insert data.  The disk space is not lost.  But
  neither is it returned to the operating system.</p>

  <p>If you delete a lot of data and want to shrink the database file,
  run the <a href="lang_vacuum.html">VACUUM</a> command.
  VACUUM will reconstruct
  the database from scratch.  This will leave the database with an empty
  free-list and a file that is minimal in size.  Note, however, that the
  VACUUM can take some time to run (around a half second per megabyte
  on the Linux box where SQLite is developed) and it can use up to twice
  as much temporary disk space as the original file while it is running.
  </p>

  <p>As of SQLite version 3.1, an alternative to using the VACUUM command
  is auto-vacuum mode, enabled using the 
  <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.</p>
}

faq {
  Can I use SQLite in my commercial product without paying royalties?
} {
  <p>Yes.  SQLite is in the 
  <a href="copyright.html">public domain</a>.  No claim of ownership is made
  to any part of the code.  You can do anything you want with it.</p>
}

faq {
  How do I use a string literal that contains an embedded single-quote (')
  character?
} {
  <p>The SQL standard specifies that single-quotes in strings are escaped
  by putting two single quotes in a row.  SQL works like the Pascal programming
  language in the regard.  SQLite follows this standard.  Example:
  </p>

  <blockquote><pre>
    INSERT INTO xyz VALUES('5 O''clock');
  </pre></blockquote>
}

faq {What is an SQLITE_SCHEMA error, and why am I getting one?} {
  <p>An SQLITE_SCHEMA error is returned when a 
  prepared SQL statement is no longer valid and cannot be executed.
  When this occurs, the statement must be recompiled from SQL using 
  the 
  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> API.
  In SQLite version 3, an SQLITE_SCHEMA error can
  only occur when using the 
  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
  href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
  href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
  API to execute SQL, not when using the
  <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>. This was not
  the case in version 2.</p>

  <p>The most common reason for a prepared statement to become invalid
  is that the schema of the database was modified after the SQL was 
  prepared (possibly by another process).  The other reasons this can 
  happen are:</p> 
  <ul>
  <li>A database was <a href="lang_detach.html">DETACH</a>ed.
  <li>The database was <a href="lang_vacuum.html">VACUUM</a>ed
  <li>A user-function definition was deleted or changed.
  <li>A collation sequence definition was deleted or changed.
  <li>The authorization function was changed.
  </ul>

  <p>In all cases, the solution is to recompile the statement from SQL
  and attempt to execute it again. Because a prepared statement can be
  invalidated by another process changing the database schema, all code
  that uses the
  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
  href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
  href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
  API should be prepared to handle SQLITE_SCHEMA errors. An example
  of one approach to this follows:</p>

  <blockquote><pre>

    int rc;
    sqlite3_stmt *pStmt;
    char zSql[] = "SELECT .....";

    do {
      /* Compile the statement from SQL. Assume success. */
      sqlite3_prepare(pDb, zSql, -1, &pStmt, 0);

      while( SQLITE_ROW==sqlite3_step(pStmt) ){
        /* Do something with the row of available data */
      }

      /* Finalize the statement. If an SQLITE_SCHEMA error has
      ** occured, then the above call to sqlite3_step() will have
      ** returned SQLITE_ERROR. sqlite3_finalize() will return
      ** SQLITE_SCHEMA. In this case the loop will execute again.
      */
      rc = sqlite3_finalize(pStmt);
    } while( rc==SQLITE_SCHEMA );
    
  </pre></blockquote>
}

faq {Why does ROUND(9.95,1)  return 9.9 instead of 10.0?
     Shouldn't 9.95 round up?} {
  <p>SQLite uses binary arithmetic and in binary, there is no
  way to write 9.95 in a finite number of bits.  The closest to
  you can get to 9.95 in a 64-bit IEEE float (which is what
  SQLite uses) is 9.949999999999999289457264239899814128875732421875.
  So when you type "9.95", SQLite really understands the number to be
  the much longer value shown above.  And that value rounds down.</p>

  <p>This kind of problem comes up all the time when dealing with
  floating point binary numbers.  The general rule to remember is
  that most fractional numbers that have a finite representation in decimal
  (a.k.a "base-10")
  do not have a finite representation in binary (a.k.a "base-2").
  And so they are
  approximated using the closest binary number available.  That
  approximation is usually very close, but it will be slightly off
  and in some cases can cause your results to be a little different
  from what you might expect.</p>
}

# End of questions and answers.
#############

puts {<h2>Frequently Asked Questions</h2>}

# puts {<DL COMPACT>}
# for {set i 1} {$i<$cnt} {incr i} {
#   puts "  <DT><A HREF=\"#q$i\">($i)</A></DT>"
#   puts "  <DD>[lindex $faq($i) 0]</DD>"
# }
# puts {</DL>}
puts {<OL>}
for {set i 1} {$i<$cnt} {incr i} {
  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
}
puts {</OL>}

for {set i 1} {$i<$cnt} {incr i} {
  puts "<A NAME=\"q$i\"><HR />"
  puts "<P><B>($i) [lindex $faq($i) 0]</B></P>\n"
  puts "<BLOCKQUOTE>[lindex $faq($i) 1]</BLOCKQUOTE></LI>\n"
}

puts {</OL>}
footer $rcsid

#
# Run this script to generated a fileformat.html output file
#
set rcsid {$Id: fileformat.tcl,v 1.13 2004/10/10 17:24:55 drh Exp $}
source common.tcl
header {SQLite Database File Format (Version 2)}
puts {
<h2>SQLite 2.X Database File Format</h2>

<p>
This document describes the disk file format for SQLite versions 2.1
through 2.8.  SQLite version 3.0 and following uses a very different
format which is described separately.
</p>

<h3>1.0 &nbsp; Layers</h3>

<p>
SQLite is implemented in layers.
(See the <a href="arch.html">architecture description</a>.)
The format of database files is determined by three different
layers in the architecture.
</p>

<ul>
<li>The <b>schema</b> layer implemented by the VDBE.</li>
<li>The <b>b-tree</b> layer implemented by btree.c</li>
<li>The <b>pager</b> layer implemented by pager.c</li>
</ul>

<p>
We will describe each layer beginning with the bottom (pager)
layer and working upwards.
</p>

<h3>2.0 &nbsp; The Pager Layer</h3>

<p>
An SQLite database consists of
"pages" of data.  Each page is 1024 bytes in size.
Pages are numbered beginning with 1.
A page number of 0 is used to indicate "no such page" in the
B-Tree and Schema layers.
</p>

<p>
The pager layer is responsible for implementing transactions
with atomic commit and rollback.  It does this using a separate
journal file.  Whenever a new transaction is started, a journal
file is created that records the original state of the database.
If the program terminates before completing the transaction, the next
process to open the database can use the journal file to restore
the database to its original state.
</p>

<p>
The journal file is located in the same directory as the database
file and has the same name as the database file but with the
characters "<tt>-journal</tt>" appended.
</p>

<p>
The pager layer does not impose any content restrictions on the
main database file.  As far as the pager is concerned, each page
contains 1024 bytes of arbitrary data.  But there is structure to
the journal file.
</p>

<p>
A journal file begins with 8 bytes as follows:
0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6.
Processes that are attempting to rollback a journal use these 8 bytes
as a sanity check to make sure the file they think is a journal really
is a valid journal.  Prior version of SQLite used different journal
file formats.  The magic numbers for these prior formats are different
so that if a new version of the library attempts to rollback a journal
created by an earlier version, it can detect that the journal uses
an obsolete format and make the necessary adjustments.  This article
describes only the newest journal format - supported as of version
2.8.0.
</p>

<p>
Following the 8 byte prefix is a three 4-byte integers that tell us
the number of pages that have been committed to the journal,
a magic number used for
sanity checking each page, and the
original size of the main database file before the transaction was
started.  The number of committed pages is used to limit how far
into the journal to read.  The use of the checksum magic number is
described below.
The original size of the database is used to restore the database
file back to its original size.
The size is expressed in pages (1024 bytes per page).
</p>

<p>
All three integers in the journal header and all other multi-byte
numbers used in the journal file are big-endian.
That means that the most significant byte
occurs first.  That way, a journal file that is
originally created on one machine can be rolled back by another
machine that uses a different byte order.  So, for example, a
transaction that failed to complete on your big-endian SparcStation
can still be rolled back on your little-endian Linux box.
</p>

<p>
After the 8-byte prefix and the three 4-byte integers, the
journal file consists of zero or more page records.  Each page
record is a 4-byte (big-endian) page number followed by 1024 bytes
of data and a 4-byte checksum.  
The data is the original content of the database page
before the transaction was started.  So to roll back the transaction,
the data is simply written into the corresponding page of the
main database file.  Pages can appear in the journal in any order,
but they are guaranteed to appear only once. All page numbers will be
between 1 and the maximum specified by the page size integer that
appeared at the beginning of the journal.
</p>

<p>
The so-called checksum at the end of each record is not really a
checksum - it is the sum of the page number and the magic number which
was the second integer in the journal header.  The purpose of this
value is to try to detect journal corruption that might have occurred
because of a power loss or OS crash that occurred which the journal
file was being written to disk.  It could have been the case that the
meta-data for the journal file, specifically the size of the file, had
been written to the disk so that when the machine reboots it appears that
file is large enough to hold the current record.  But even though the
file size has changed, the data for the file might not have made it to
the disk surface at the time of the OS crash or power loss.  This means
that after reboot, the end of the journal file will contain quasi-random
garbage data.  The checksum is an attempt to detect such corruption.  If
the checksum does not match, that page of the journal is not rolled back.
</p>

<p>
Here is a summary of the journal file format:
</p>

<ul>
<li>8 byte prefix: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd6</li>
<li>4 byte number of records in journal</li>
<li>4 byte magic number used for page checksums</li>
<li>4 byte initial database page count</li>
<li>Zero or more instances of the following:
   <ul>
   <li>4 byte page number</li>
   <li>1024 bytes of original data for the page</li>
   <li>4 byte checksum</li>
   </ul>
</li>
</ul>

<h3>3.0 &nbsp; The B-Tree Layer</h3>

<p>
The B-Tree layer builds on top of the pager layer to implement
one or more separate b-trees all in the same disk file.  The
algorithms used are taken from Knuth's <i>The Art Of Computer
Programming.</i></p>

<p>
Page 1 of a database contains a header string used for sanity
checking, a few 32-bit words of configuration data, and a pointer
to the beginning of a list of unused pages in the database.
All other pages in the
database are either pages of a b-tree, overflow pages, or unused
pages on the freelist.
</p>

<p>
Each b-tree page contains zero or more database entries.
Each entry has an unique key of one or more bytes and data of
zero or more bytes.
Both the key and data are arbitrary byte sequences.  The combination
of key and data are collectively known as "payload".  The current
implementation limits the amount of payload in a single entry to
1048576 bytes.  This limit can be raised to 16777216 by adjusting
a single #define in the source code and recompiling.  But most entries
contain less than a hundred bytes of payload so a megabyte limit seems
more than enough.
</p>

<p>
Up to 238 bytes of payload for an entry can be held directly on
a b-tree page.  Any additional payload is contained on a linked list
of overflow pages.  This limit on the amount of payload held directly
on b-tree pages guarantees that each b-tree page can hold at least
4 entries.  In practice, most entries are smaller than 238 bytes and
thus most pages can hold more than 4 entries.
</p>

<p>
A single database file can hold any number of separate, independent b-trees.
Each b-tree is identified by its root page, which never changes.
Child pages of the b-tree may change as entries are added and removed
and pages split and combine.  But the root page always stays the same.
The b-tree itself does not record which pages are root pages and which
are not.  That information is handled entirely at the schema layer.
</p>

<h4>3.1 &nbsp; B-Tree Page 1 Details</h4>

<p>
Page 1 begins with the following 48-byte string:
</p>

<blockquote><pre>
** This file contains an SQLite 2.1 database **
</pre></blockquote>

<p>
If you count the number of characters in the string above, you will
see that there are only 47.  A '\000' terminator byte is added to
bring the total to 48.
</p>

<p>
A frequent question is why the string says version 2.1 when (as
of this writing) we are up to version 2.7.0 of SQLite and any
change to the second digit of the version is suppose to represent
a database format change.  The answer to this is that the B-tree
layer has not changed any since version 2.1.  There have been
database format changes since version 2.1 but those changes have
all been in the schema layer.  Because the format of the b-tree
layer is unchanged since version 2.1.0, the header string still
says version 2.1.
</p>

<p>
After the format string is a 4-byte integer used to determine the
byte-order of the database.  The integer has a value of
0xdae37528.  If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then
the database is in a big-endian format and all 16 and 32-bit integers
elsewhere in the b-tree layer are also big-endian.  If the number is
expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a
little-endian format and all other multi-byte numbers in the b-tree 
layer are also little-endian.  
Prior to version 2.6.3, the SQLite engine was only able to read databases
that used the same byte order as the processor they were running on.
But beginning with 2.6.3, SQLite can read or write databases in any
byte order.
</p>

<p>
After the byte-order code are six 4-byte integers.  Each integer is in the
byte order determined by the byte-order code.  The first integer is the
page number for the first page of the freelist.  If there are no unused
pages in the database, then this integer is 0.  The second integer is
the number of unused pages in the database.  The last 4 integers are
not used by the b-tree layer.  These are the so-called "meta" values that
are passed up to the schema layer
and used there for configuration and format version information.
All bytes of page 1 past beyond the meta-value integers are unused 
and are initialized to zero.
</p>

<p>
Here is a summary of the information contained on page 1 in the b-tree layer:
</p>

<ul>
<li>48 byte header string</li>
<li>4 byte integer used to determine the byte-order</li>
<li>4 byte integer which is the first page of the freelist</li>
<li>4 byte integer which is the number of pages on the freelist</li>
<li>36 bytes of meta-data arranged as nine 4-byte integers</li>
<li>928 bytes of unused space</li>
</ul>

<h4>3.2 &nbsp; Structure Of A Single B-Tree Page</h4>

<p>
Conceptually, a b-tree page contains N database entries and N+1 pointers
to other b-tree pages.
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center">Ptr<br>0</td>
<td align="center">Entry<br>0</td>
<td align="center">Ptr<br>1</td>
<td align="center">Entry<br>1</td>
<td align="center"><b>...</b></td>
<td align="center">Ptr<br>N-1</td>
<td align="center">Entry<br>N-1</td>
<td align="center">Ptr<br>N</td>
</tr>
</table>
</blockquote>

<p>
The entries are arranged in increasing order.  That is, the key to
Entry 0 is less than the key to Entry 1, and the key to Entry 1 is
less than the key of Entry 2, and so forth.  The pointers point to
pages containing additional entries that have keys in between the
entries on either side.  So Ptr 0 points to another b-tree page that
contains entries that all have keys less than Key 0, and Ptr 1
points to a b-tree pages where all entries have keys greater than Key 0
but less than Key 1, and so forth.
</p>

<p>
Each b-tree page in SQLite consists of a header, zero or more "cells"
each holding a single entry and pointer, and zero or more "free blocks"
that represent unused space on the page.
</p>

<p>
The header on a b-tree page is the first 8 bytes of the page.
The header contains the value
of the right-most pointer (Ptr N) and the byte offset into the page
of the first cell and the first free block.  The pointer is a 32-bit
value and the offsets are each 16-bit values.  We have:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center" width=30>0</td>
<td align="center" width=30>1</td>
<td align="center" width=30>2</td>
<td align="center" width=30>3</td>
<td align="center" width=30>4</td>
<td align="center" width=30>5</td>
<td align="center" width=30>6</td>
<td align="center" width=30>7</td>
</tr>
<tr>
<td align="center" colspan=4>Ptr N</td>
<td align="center" colspan=2>Cell 0</td>
<td align="center" colspan=2>Freeblock 0</td>
</tr>
</table>
</blockquote>

<p>
The 1016 bytes of a b-tree page that come after the header contain
cells and freeblocks.  All 1016 bytes are covered by either a cell
or a freeblock.
</p>

<p>
The cells are connected in a linked list.  Cell 0 contains Ptr 0 and
Entry 0.  Bytes 4 and 5 of the header point to Cell 0.  Cell 0 then
points to Cell 1 which contains Ptr 1 and Entry 1.  And so forth.
Cells vary in size.  Every cell has a 12-byte header and at least 4
bytes of payload space.  Space is allocated to payload in increments
of 4 bytes.  Thus the minimum size of a cell is 16 bytes and up to
63 cells can fit on a single page.  The size of a cell is always a multiple
of 4 bytes.
A cell can have up to 238 bytes of payload space.  If
the payload is more than 238 bytes, then an additional 4 byte page
number is appended to the cell which is the page number of the first
overflow page containing the additional payload.  The maximum size
of a cell is thus 254 bytes, meaning that a least 4 cells can fit into
the 1016 bytes of space available on a b-tree page.
An average cell is usually around 52 to 100 bytes in size with about
10 or 20 cells to a page.
</p>

<p>
The data layout of a cell looks like this:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center" width=20>0</td>
<td align="center" width=20>1</td>
<td align="center" width=20>2</td>
<td align="center" width=20>3</td>
<td align="center" width=20>4</td>
<td align="center" width=20>5</td>
<td align="center" width=20>6</td>
<td align="center" width=20>7</td>
<td align="center" width=20>8</td>
<td align="center" width=20>9</td>
<td align="center" width=20>10</td>
<td align="center" width=20>11</td>
<td align="center" width=100>12 ... 249</td>
<td align="center" width=20>250</td>
<td align="center" width=20>251</td>
<td align="center" width=20>252</td>
<td align="center" width=20>253</td>
</tr>
<tr>
<td align="center" colspan=4>Ptr</td>
<td align="center" colspan=2>Keysize<br>(low)</td>
<td align="center" colspan=2>Next</td>
<td align="center" colspan=1>Ksz<br>(hi)</td>
<td align="center" colspan=1>Dsz<br>(hi)</td>
<td align="center" colspan=2>Datasize<br>(low)</td>
<td align="center" colspan=1>Payload</td>
<td align="center" colspan=4>Overflow<br>Pointer</td>
</tr>
</table>
</blockquote>

<p>
The first four bytes are the pointer.  The size of the key is a 24-bit
where the upper 8 bits are taken from byte 8 and the lower 16 bits are
taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.)
The size of the data is another 24-bit value where the upper 8 bits
are taken from byte 9 and the lower 16 bits are taken from bytes 10 and
11 or 11 and 10, depending on the byte order.  Bytes 6 and 7 are the
offset to the next cell in the linked list of all cells on the current
page.  This offset is 0 for the last cell on the page.
</p>

<p>
The payload itself can be any number of bytes between 1 and 1048576.
But space to hold the payload is allocated in 4-byte chunks up to
238 bytes.  If the entry contains more than 238 bytes of payload, then
additional payload data is stored on a linked list of overflow pages.
A 4 byte page number is appended to the cell that contains the first
page of this linked list.
</p>

<p>
Each overflow page begins with a 4-byte value which is the
page number of the next overflow page in the list.   This value is
0 for the last page in the list.  The remaining
1020 bytes of the overflow page are available for storing payload.
Note that a full page is allocated regardless of the number of overflow
bytes stored.  Thus, if the total payload for an entry is 239 bytes,
the first 238 are stored in the cell and the overflow page stores just
one byte.
</p>

<p>
The structure of an overflow page looks like this:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center" width=20>0</td>
<td align="center" width=20>1</td>
<td align="center" width=20>2</td>
<td align="center" width=20>3</td>
<td align="center" width=200>4 ... 1023</td>
</tr>
<tr>
<td align="center" colspan=4>Next Page</td>
<td align="center" colspan=1>Overflow Data</td>
</tr>
</table>
</blockquote>

<p>
All space on a b-tree page which is not used by the header or by cells
is filled by freeblocks.  Freeblocks, like cells, are variable in size.
The size of a freeblock is at least 4 bytes and is always a multiple of
4 bytes.
The first 4 bytes contain a header and the remaining bytes
are unused.  The structure of the freeblock is as follows:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center" width=20>0</td>
<td align="center" width=20>1</td>
<td align="center" width=20>2</td>
<td align="center" width=20>3</td>
<td align="center" width=200>4 ... 1015</td>
</tr>
<tr>
<td align="center" colspan=2>Size</td>
<td align="center" colspan=2>Next</td>
<td align="center" colspan=1>Unused</td>
</tr>
</table>
</blockquote>

<p>
Freeblocks are stored in a linked list in increasing order.  That is
to say, the first freeblock occurs at a lower index into the page than
the second free block, and so forth.  The first 2 bytes of the header
are an integer which is the total number of bytes in the freeblock.
The second 2 bytes are the index into the page of the next freeblock
in the list.  The last freeblock has a Next value of 0.
</p>

<p>
When a new b-tree is created in a database, the root page of the b-tree
consist of a header and a single 1016 byte freeblock.  As entries are
added, space is carved off of that freeblock and used to make cells.
When b-tree entries are deleted, the space used by their cells is converted
into freeblocks.  Adjacent freeblocks are merged, but the page can still
become fragmented.  The b-tree code will occasionally try to defragment
the page by moving all cells to the beginning and constructing a single
freeblock at the end to take up all remaining space.
</p>

<h4>3.3 &nbsp; The B-Tree Free Page List</h4>

<p>
When information is removed from an SQLite database such that one or
more pages are no longer needed, those pages are added to a list of
free pages so that they can be reused later when new information is
added.  This subsection describes the structure of this freelist.
</p>

<p>
The 32-bit integer beginning at byte-offset 52 in page 1 of the database
contains the address of the first page in a linked list of free pages.
If there are no free pages available, this integer has a value of 0.
The 32-bit integer at byte-offset 56 in page 1 contains the number of
free pages on the freelist.
</p>

<p>
The freelist contains a trunk and many branches.  The trunk of
the freelist is composed of overflow pages.  That is to say, each page
contains a single 32-bit integer at byte offset 0 which
is the page number of the next page on the freelist trunk.
The payload area
of each trunk page is used to record pointers to branch pages. 
The first 32-bit integer in the payload area of a trunk page
is the number of branch pages to follow (between 0 and 254)
and each subsequent 32-bit integer is a page number for a branch page.
The following diagram shows the structure of a trunk freelist page:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td align="center" width=20>0</td>
<td align="center" width=20>1</td>
<td align="center" width=20>2</td>
<td align="center" width=20>3</td>
<td align="center" width=20>4</td>
<td align="center" width=20>5</td>
<td align="center" width=20>6</td>
<td align="center" width=20>7</td>
<td align="center" width=200>8 ... 1023</td>
</tr>
<tr>
<td align="center" colspan=4>Next trunk page</td>
<td align="center" colspan=4># of branch pages</td>
<td align="center" colspan=1>Page numbers for branch pages</td>
</tr>
</table>
</blockquote>

<p>
It is important to note that only the pages on the trunk of the freelist
contain pointers to other pages.  The branch pages contain no
data whatsoever.  The fact that the branch pages are completely
blank allows for an important optimization in the paging layer.  When
a branch page is removed from the freelist to be reused, it is not
necessary to write the original content of that page into the rollback
journal.  The branch page contained no data to begin with, so there is
no need to restore the page in the event of a rollback.  Similarly,
when a page is not longer needed and is added to the freelist as a branch
page, it is not necessary to write the content of that page
into the database file.
Again, the page contains no real data so it is not necessary to record the
content of that page.  By reducing the amount of disk I/O required,
these two optimizations allow some database operations
to go four to six times faster than they would otherwise.
</p>

<h3>4.0 &nbsp; The Schema Layer</h3>

<p>
The schema layer implements an SQL database on top of one or more
b-trees and keeps track of the root page numbers for all b-trees.
Where the b-tree layer provides only unformatted data storage with
a unique key, the schema layer allows each entry to contain multiple
columns.  The schema layer also allows indices and non-unique key values.
</p>

<p>
The schema layer implements two separate data storage abstractions:
tables and indices.  Each table and each index uses its own b-tree
but they use the b-tree capabilities in different ways.  For a table,
the b-tree key is a unique 4-byte integer and the b-tree data is the
content of the table row, encoded so that columns can be separately
extracted.  For indices, the b-tree key varies in size depending on the
size of the fields being indexed and the b-tree data is empty.
</p>

<h4>4.1 &nbsp; SQL Table Implementation Details</h4>

<p>Each row of an SQL table is stored in a single b-tree entry.
The b-tree key is a 4-byte big-endian integer that is the ROWID
or INTEGER PRIMARY KEY for that table row.
The key is stored in a big-endian format so
that keys will sort in numerical order using memcmp() function.</p>

<p>The content of a table row is stored in the data portion of
the corresponding b-tree table.  The content is encoded to allow
individual columns of the row to be extracted as necessary.  Assuming
that the table has N columns, the content is encoded as N+1 offsets
followed by N column values, as follows:
</p>

<blockquote>
<table border=1 cellspacing=0 cellpadding=5>
<tr>
<td>offset 0</td>
<td>offset 1</td>
<td><b>...</b></td>
<td>offset N-1</td>
<td>offset N</td>
<td>value 0</td>
<td>value 1</td>
<td><b>...</b></td>
<td>value N-1</td>
</tr>
</table>
</blockquote>

<p>
The offsets can be either 8-bit, 16-bit, or 24-bit integers depending
on how much data is to be stored.  If the total size of the content
is less than 256 bytes then 8-bit offsets are used.  If the total size
of the b-tree data is less than 65536 then 16-bit offsets are used.
24-bit offsets are used otherwise.  Offsets are always little-endian,
which means that the least significant byte occurs first.
</p>

<p>
Data is stored as a nul-terminated string.  Any empty string consists
of just the nul terminator.  A NULL value is an empty string with no
nul-terminator.  Thus a NULL value occupies zero bytes and an empty string
occupies 1 byte.
</p>

<p>
Column values are stored in the order that they appear in the CREATE TABLE
statement.  The offsets at the beginning of the record contain the
byte index of the corresponding column value.  Thus, Offset 0 contains
the byte index for Value 0, Offset 1 contains the byte offset
of Value 1, and so forth.  The number of bytes in a column value can
always be found by subtracting offsets.  This allows NULLs to be
recovered from the record unambiguously.
</p>

<p>
Most columns are stored in the b-tree data as described above.
The one exception is column that has type INTEGER PRIMARY KEY.
INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key.
When an SQL statement attempts to read the INTEGER PRIMARY KEY,
the 4-byte b-tree key is read rather than information out of the
b-tree data.  But there is still an Offset associated with the
INTEGER PRIMARY KEY, just like any other column.  But the Value
associated with that offset is always NULL.
</p>

<h4>4.2 &nbsp; SQL Index Implementation Details</h4>

<p>
SQL indices are implement using a b-tree in which the key is used
but the data is always empty.  The purpose of an index is to map
one or more column values into the ROWID for the table entry that
contains those column values.
</p>

<p>
Each b-tree in an index consists of one or more column values followed
by a 4-byte ROWID.  Each column value is nul-terminated (even NULL values)
and begins with a single character that indicates the datatype for that
column value.  Only three datatypes are supported: NULL, Number, and
Text.  NULL values are encoded as the character 'a' followed by the
nul terminator.  Numbers are encoded as the character 'b' followed by
a string that has been crafted so that sorting the string using memcmp()
will sort the corresponding numbers in numerical order.  (See the
sqliteRealToSortable() function in util.c of the SQLite sources for
additional information on this encoding.)  Numbers are also nul-terminated.
Text values consists of the character 'c' followed by a copy of the
text string and a nul-terminator.  These encoding rules result in
NULLs being sorted first, followed by numerical values in numerical
order, followed by text values in lexicographical order.
</p>

<h4>4.4 &nbsp; SQL Schema Storage And Root B-Tree Page Numbers</h4>

<p>
The database schema is stored in the database in a special tabled named
"sqlite_master" and which always has a root b-tree page number of 2.
This table contains the original CREATE TABLE,
CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define
the database to begin with.  Whenever an SQLite database is opened,
the sqlite_master table is scanned from beginning to end and 
all the original CREATE statements are played back through the parser
in order to reconstruct an in-memory representation of the database
schema for use in subsequent command parsing.  For each CREATE TABLE
and CREATE INDEX statement, the root page number for the corresponding
b-tree is also recorded in the sqlite_master table so that SQLite will
know where to look for the appropriate b-tree.
</p>

<p>
SQLite users can query the sqlite_master table just like any other table
in the database.  But the sqlite_master table cannot be directly written.
The sqlite_master table is automatically updated in response to CREATE
and DROP statements but it cannot be changed using INSERT, UPDATE, or
DELETE statements as that would risk corrupting the database.
</p>

<p>
SQLite stores temporary tables and indices in a separate
file from the main database file.  The temporary table database file
is the same structure as the main database file.  The schema table
for the temporary tables is stored on page 2 just as in the main
database.  But the schema table for the temporary database named
"sqlite_temp_master" instead of "sqlite_master".  Other than the
name change, it works exactly the same.
</p>

<h4>4.4 &nbsp; Schema Version Numbering And Other Meta-Information</h4>

<p>
The nine 32-bit integers that are stored beginning at byte offset
60 of Page 1 in the b-tree layer are passed up into the schema layer
and used for versioning and configuration information.  The meaning
of the first four integers is shown below.  The other five are currently
unused.
</p>

<ol>
<li>The schema version number</li>
<li>The format version number</li>
<li>The recommended pager cache size</li>
<li>The safety level</li>
</ol>

<p>
The first meta-value, the schema version number, is used to detect when
the schema of the database is changed by a CREATE or DROP statement.
Recall that when a database is first opened the sqlite_master table is
scanned and an internal representation of the tables, indices, views,
and triggers for the database is built in memory.  This internal
representation is used for all subsequent SQL command parsing and
execution.  But what if another process were to change the schema
by adding or removing a table, index, view, or trigger?  If the original
process were to continue using the old schema, it could potentially
corrupt the database by writing to a table that no longer exists.
To avoid this problem, the schema version number is changed whenever
a CREATE or DROP statement is executed.  Before each command is
executed, the current schema version number for the database file
is compared against the schema version number from when the sqlite_master
table was last read.  If those numbers are different, the internal
schema representation is erased and the sqlite_master table is reread
to reconstruct the internal schema representation.
(Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.)
</p>

<p>
The second meta-value is the schema format version number.  This
number tells what version of the schema layer should be used to
interpret the file.  There have been changes to the schema layer
over time and this number is used to detect when an older database
file is being processed by a newer version of the library.
As of this writing (SQLite version 2.7.0) the current format version
is "4".
</p>

<p>
The third meta-value is the recommended pager cache size as set 
by the DEFAULT_CACHE_SIZE pragma.  If the value is positive it
means that synchronous behavior is enable (via the DEFAULT_SYNCHRONOUS
pragma) and if negative it means that synchronous behavior is
disabled.
</p>

<p>
The fourth meta-value is safety level added in version 2.8.0.
A value of 1 corresponds to a SYNCHRONOUS setting of OFF.  In other
words, SQLite does not pause to wait for journal data to reach the disk
surface before overwriting pages of the database.  A value of 2 corresponds
to a SYNCHRONOUS setting of NORMAL.  A value of 3 corresponds to a
SYNCHRONOUS setting of FULL. If the value is 0, that means it has not
been initialized so the default synchronous setting of NORMAL is used.
</p>
}
footer $rcsid