Documentation Source Text

<li> Automatically intercepts the raw [EXPLAIN QUERY PLAN] 
     output and reformats it into an ASCII-art graph.
<li> Lines that begin with "#" and that are not in the middle of an
     SQL statement are interpreted as comments.
<li> Added the --append option to the ".backup" command.
<li> Added the ".dbconfig" command.
<p><b>Performance:</b>
<li> [UPDATE] avoids writing database pages that do not actually change.

     For example, "UPDATE t1 SET x=25 WHERE y=?" becomes a no-op if the
     value in column x is already 25.  Similarly, 
     when doing [UPDATE] on records that span multiple pages, only write
     the subset of pages that contain the changed value(s).



<li> Queries that use ORDER BY and LIMIT now try to avoid computing
     rows that cannot possibly come in under the LIMIT. This can greatly
     improve performance of ORDER BY LIMIT queries, especially when the
     LIMIT is small relative to the number of unrestricted output rows.
<li> The [OR optimization] is allowed to proceed
     even if the OR expression has also been converted into an IN
     expression.  Uses of the OR optimization are now also 

<li> Automatically intercepts the raw [EXPLAIN QUERY PLAN] 
     output and reformats it into an ASCII-art graph.
<li> Lines that begin with "#" and that are not in the middle of an
     SQL statement are interpreted as comments.
<li> Added the --append option to the ".backup" command.
<li> Added the ".dbconfig" command.
<p><b>Performance:</b>
<li> [UPDATE] avoids unnecessary low-level disk writes when the contents
     of the database file do not actually change.
     For example, "UPDATE t1 SET x=25 WHERE y=?" generates no extra 
     disk I/O if the value in column x is already 25.  Similarly, 
     when doing [UPDATE] on records that span multiple pages, only
     the subset of pages that actually change are written to disk.
     This is a low-level performance optimization only and does not
     affect the behavior of TRIGGERs or other higher level SQL
     structures.
<li> Queries that use ORDER BY and LIMIT now try to avoid computing
     rows that cannot possibly come in under the LIMIT. This can greatly
     improve performance of ORDER BY LIMIT queries, especially when the
     LIMIT is small relative to the number of unrestricted output rows.
<li> The [OR optimization] is allowed to proceed
     even if the OR expression has also been converted into an IN
     expression.  Uses of the OR optimization are now also 

  The default sorting procedure is to gather all information that will
  ultimately be output into a "record" and pass that complete record
  to the sorter.  But in some cases, for example if some of the output
  columns consists of large BLOB values, the size of the each record
  can be large, which means that the sorter has to either use more memory,
  and/or write more content to temporary storage.
  <p>
  When SQLITE_ENABLE_SORTER_PREFERENCES is enabled, the records passed to
  the sorter often contain only a [ROWID] value.  Such records are much
  smaller.  This means the sorter has much less "payload" to deal with and
  can run faster.  After sorting has occurred, the ROWID is used to look up 
  the output column values in the original table.  That requires another
  search into the table, and could potentially result in a slowdown.  Or,
  it might be a performance win, depending on how large the values are.
  <p>
  Even when the SQLITE_ENABLE_SORTER_PREFERENCES compile-time option is on,
  sorter references are still disabled by default.  To use sorter references,
  the application must set a sorter reference size threshold using the
  [sqlite3_config]([SQLITE_CONFIG_SORTERREF_SIZE]) interface at start-time.
  <p>
  Because the SQLite developers do not know whether the 
  SQLITE_ENABLE_SORTER_PERFERENCES option will help or hurt performance,
  it is disabled by default at this time (2018-05-04).  It might be enabled
  by default in some future release, depending on what is learned about its
  inpact on performance.
}

COMPILE_OPTION {SQLITE_ENABLE_STMT_SCANSTATUS} {
  This option enables the [sqlite3_stmt_scanstatus()] interface.  The
  [sqlite3_stmt_scanstatus()] interface is normally omitted from the build
  because it imposes a small performance penalty, even on statements that
  do not use the feature.

  The default sorting procedure is to gather all information that will
  ultimately be output into a "record" and pass that complete record
  to the sorter.  But in some cases, for example if some of the output
  columns consists of large BLOB values, the size of the each record
  can be large, which means that the sorter has to either use more memory,
  and/or write more content to temporary storage.
  <p>
  When SQLITE_ENABLE_SORTER_REFERENCES is enabled, the records passed to
  the sorter often contain only a [ROWID] value.  Such records are much
  smaller.  This means the sorter has much less "payload" to deal with and
  can run faster.  After sorting has occurred, the ROWID is used to look up 
  the output column values in the original table.  That requires another
  search into the table, and could potentially result in a slowdown.  Or,
  it might be a performance win, depending on how large the values are.
  <p>
  Even when the SQLITE_ENABLE_SORTER_REFERENCES compile-time option is on,
  sorter references are still disabled by default.  To use sorter references,
  the application must set a sorter reference size threshold using the
  [sqlite3_config]([SQLITE_CONFIG_SORTERREF_SIZE]) interface at start-time.
  <p>
  Because the SQLite developers do not know whether the 
  SQLITE_ENABLE_SORTER_REFERENCES option will help or hurt performance,
  it is disabled by default at this time (2018-05-04).  It might be enabled
  by default in some future release, depending on what is learned about its
  impact on performance.
}

COMPILE_OPTION {SQLITE_ENABLE_STMT_SCANSTATUS} {
  This option enables the [sqlite3_stmt_scanstatus()] interface.  The
  [sqlite3_stmt_scanstatus()] interface is normally omitted from the build
  because it imposes a small performance penalty, even on statements that
  do not use the feature.

<p>In this last example, the phonebook2 entry is only
updated if the validDate for the newly inserted value is
newer than the entry already in the table.  If the table already
contains an entry with the same name and a current validDate,
then the WHERE clause causes the DO UPDATE to become a no-op.






<tcl>
##############################################################################
Section {ON CONFLICT clause} conflict {{conflict clause} {ON CONFLICT}}

RecursiveBubbleDiagram conflict-clause
</tcl>

<p>In this last example, the phonebook2 entry is only
updated if the validDate for the newly inserted value is
newer than the entry already in the table.  If the table already
contains an entry with the same name and a current validDate,
then the WHERE clause causes the DO UPDATE to become a no-op.

<h3>Limitations</h3>

<p>UPSERT does not currently work for [virtual tables].


<tcl>
##############################################################################
Section {ON CONFLICT clause} conflict {{conflict clause} {ON CONFLICT}}

RecursiveBubbleDiagram conflict-clause
</tcl>

destructor for client data pointer.  The module structure is what defines
the behavior of a virtual table.  The module structure looks like this:

<codeblock>  
  struct sqlite3_module {
    int iVersion;
    int (*xCreate)(sqlite3*, void *pAux,
                 int argc, char **argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xConnect)(sqlite3*, void *pAux,
                 int argc, char **argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
    int (*xDisconnect)(sqlite3_vtab *pVTab);
    int (*xDestroy)(sqlite3_vtab *pVTab);
    int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
    int (*xClose)(sqlite3_vtab_cursor*);
................................................................................
<h1>Virtual Table Methods</h1>

<tcl>hd_fragment xcreate {sqlite3_module.xCreate} {xCreate}</tcl>
<h2>The xCreate Method</h2>

<codeblock>
  int (*xCreate)(sqlite3 *db, void *pAux,
               int argc, char **argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);
</codeblock>

<p>The xCreate method is called to create a new instance of a virtual table 
in response to a [CREATE VIRTUAL TABLE] statement.
If the xCreate method is the same pointer as the [xConnect] method, then the
................................................................................

<tcl>############################################################# xConnect
hd_fragment xconnect {sqlite3_module.xConnect} {xConnect}</tcl>
<h2>The xConnect Method</h2>

<codeblock>
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, char **argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);
</codeblock>

<p>The xConnect method is very similar to [xCreate]. 
It has the same parameters and constructs a new [sqlite3_vtab] structure 
just like xCreate. 

destructor for client data pointer.  The module structure is what defines
the behavior of a virtual table.  The module structure looks like this:

<codeblock>  
  struct sqlite3_module {
    int iVersion;
    int (*xCreate)(sqlite3*, void *pAux,
                 int argc, char *const*argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xConnect)(sqlite3*, void *pAux,
                 int argc, char *const*argv,
                 sqlite3_vtab **ppVTab,
                 char **pzErr);
    int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
    int (*xDisconnect)(sqlite3_vtab *pVTab);
    int (*xDestroy)(sqlite3_vtab *pVTab);
    int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
    int (*xClose)(sqlite3_vtab_cursor*);
................................................................................
<h1>Virtual Table Methods</h1>

<tcl>hd_fragment xcreate {sqlite3_module.xCreate} {xCreate}</tcl>
<h2>The xCreate Method</h2>

<codeblock>
  int (*xCreate)(sqlite3 *db, void *pAux,
               int argc, char *const*argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);
</codeblock>

<p>The xCreate method is called to create a new instance of a virtual table 
in response to a [CREATE VIRTUAL TABLE] statement.
If the xCreate method is the same pointer as the [xConnect] method, then the
................................................................................

<tcl>############################################################# xConnect
hd_fragment xconnect {sqlite3_module.xConnect} {xConnect}</tcl>
<h2>The xConnect Method</h2>

<codeblock>
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, char *const*argv,
               sqlite3_vtab **ppVTab,
               char **pzErr);
</codeblock>

<p>The xConnect method is very similar to [xCreate]. 
It has the same parameters and constructs a new [sqlite3_vtab] structure 
just like xCreate.