Documentation Source Text

It is available as a [loadable extension] in the
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/carray.c|ext/misc/carray.c]
source file.

<p>The carray() function is dangerous.  The first parameter is
a 64-bit integer which gets cast into a pointer to an array.  In an
application that runs user-generated or untrusted SQL, the carray()
function could be used to crash the application or to leak sensitive 
information.  For that
reason, the carray() function will never be a standard part of SQLite.
Carray() will only be available in applications that 
deliberately request it.  Presumably, applications that deliberately
link carray() will also have protections in place to prevent carray()
from being misused.

proc chng {date desc {options {}}} {
  global nChng aChng xrefChng
  set aChng($nChng) [list $date $desc $options]
  set xrefChng($date) $nChng
  incr nChng
}

chng {2016-08-08 (3.14)} {
<div style="width:280px;float:right;padding:10px;margin:0px 10px;">
<img src='ROOT/images/sqlitepie.jpg' width=280 height=250></img><br>
<center>Celebrating the SQLite "&#960; release"
with a home-baked pie.</center>
</div>
<li>Added support for [WITHOUT ROWID virtual tables].
<li>Improved the query planner so that the [OR optimization] can
    be used on [virtual tables] even if one or more of the disjuncts
    use the [LIKE], [GLOB], [REGEXP], [MATCH] operators.
<li>Added the [CSV virtual table] for reading
    [https://www.ietf.org/rfc/rfc4180.txt|RFC 4180] formatted comma-separated
    value files.

    parameter which is the threshold below which cache spilling is prohibited.
<li>On unix, if a symlink to a database file is opened, then the corresponding
    journal files are based on the actual filename, not the symlink name.
<li>Added the "--transaction" option to [sqldiff].
<li>Added the [sqlite3_db_cacheflush()] interface.
<li>Added the [sqlite3_strlike()] interface.
<li>When using [memory-mapped I/O] map the database file read-only so that stray pointers
    and/or array overruns in the application cannot accidentally modify the database file.
<li>Added the <em>experimental</em> [sqlite3_snapshot_get()], [sqlite3_snapshot_open()],
    and [sqlite3_snapshot_free()] interfaces.  These are subject to change or removal in
    a subsequent release.
<li>Enhance the ['utc' modifier] in the [date and time functions] so that it is a no-op if
    the date/time is known to already be in UTC.  (This is not a compatibility break since
    the behavior has long been documented as "undefined" in that case.)
<li>Added the [json_group_array()] and [json_group_object()] SQL functions in the
    [json] extension.
<li>Added the [SQLITE_LIKE_DOESNT_MATCH_BLOBS] compile-time option.
<li>Many small performance optimizations.
<p><b>Portability enhancements:</b>
<li>Work around a sign-extension bug in the optimizer of the HP C compiler on HP/UX.
    [https://www.sqlite.org/src/fdiff?sbs=1&v1=869c95b0fc73026d&v2=232c242a0ccb3d67|(details)]
<p><b>Enhancements to the [command-line shell]:</b>
<li>Added the ".changes ON|OFF" and ".vfsinfo" [dot-commands].
<li>Translate between MBCS and UTF8 when
    running in [https://en.wikipedia.org/wiki/Cmd.exe|cmd.exe] on Windows.
<p><b>Enhancements to makefiles:</b>
<li>Added the --enable-editline and --enable-static-shell options

for {set i 0} {$i<$nChng} {incr i} {
  foreach {date desc options} $aChng($i) break
  if {[regexp {\(([0-9.]+)\)} $date all vers]} {
    set label [string map {. _} $vers]
    hd_fragment version_$label
  }
  hd_puts "<h3>$date</h3>"
  regsub -all {\yROOT/\y} $desc {} d2
  hd_resolve "<p><ul>$d2\n"
  foreach {key value} $options {
    if {$key=="backport"} {
      if {[info exists xrefChng($value)]} {set value $xrefChng($value)}
      set c2 $aChng([expr {$i+$value}])
      regexp {([-0-9]+) \((3\.\d+[.0-9]+)[ a-zA-Z]*\)} [lindex $c2 0] all xdate xvers
      set d2 [lindex $c2 1]
      regsub {(<p>[^\n]*\n)?<li>SQLITE_SOURCE_ID.*$} $d2 {} d2
      hd_resolve "<p><b>Bug fixes backported into patch release $xvers ($xdate):</b></p>\n"
      hd_resolve "$d2\n"
    }
  }
  hd_resolve "</ul></p>\n"
  if {[regexp {([-0-9]+) \((3\.\d+[.0-9]+)[ a-zA-Z]*\)} $date all dateonly vers]} {
    set tag [string trim [string map {. _} $vers]]
    file mkdir $DEST/releaselog
    set filename releaselog/$tag.html
    hd_open_aux $filename
    hd_header "SQLite Release $vers On $dateonly"
    if {[regexp {3\.\d+$} $vers]} {
      hd_keywords "Version $vers.0" "*version $vers.0" "Version $vers" "*version $vers"
    } else {
      hd_keywords "Version $vers" "*version $vers"
    }
    hd_enable_main 0
    hd_puts "<h2>SQLite Release $vers On $dateonly</h2>"
    regsub -all {<a href="(?!http:)} $desc {<a href="../} desc
    foreach {key value} $options {
      if {$key=="inadditionto"} {
        set d2 [lindex $aChng([expr {$i+$value}]) 1]
        regsub {(<p>[^\n]*\n)?<li>SQLITE_SOURCE_ID.*$} $d2 {} d2
        hd_resolve "<p><ul>$d2</ul></p>"
      }
    }
    regsub -all {\yROOT/\y} $desc {../} d2
    hd_resolve "<p><ul>$d2\n"
    foreach {key value} $options {
      if {$key=="patchagainst"} {
        if {[info exists xrefChng($value)]} {set value $xrefChng($value)}
        set c2 $aChng([expr {$i+$value}])
        regexp {([-0-9]+) \((3\.\d+\.[.0-9]+)[ a-zA-Z]*\)} [lindex $c2 0] all date vers
        set d2 [lindex $c2 1]
        regsub {(<p>[^\n]*\n)?<li>SQLITE_SOURCE_ID.*$} $d2 {} d2

</tcl>
<a name="linkage"></a>
<h2>1.10 Compiler Linkage Control</h2>

<p>The following macros specify
interface linkage for certain kinds of SQLite builds.  The Makefiles will normally
handle setting these macros automatically.  Application developers should
not need to worry with these macros.  The following documentation about these 
macros is included completeness.</p>

<tcl>
COMPILE_OPTION {SQLITE_API} {
  This macro identifies a externally visible interface for SQLite.
  This macro is sometimes set to "extern".  But the definition is
  compiler-specific.

  authority TEXT,
  comment TEXT
);
CREATE INDEX acctchng_magnitude ON account_change(acct_no, abs(amt));
</pre></blockquote>

<p>
Each entry in the account_change table records a deposit or a withdrawal
into an account.  Deposits have a positive "amt" and withdrawals have
a negative "amt".

<p>
The acctchng_magnitude index is over the account number ("acct_no") and
on the absolute value of the amount.  This index allows one to do 
efficient queries over the magnitude of a change to the account.
For example, to list all changes to account number $xyz that are

<ol>
<li><p>
Expressions in CREATE INDEX statements
may only refer to columns of the table being indexed, not to
columns in other tables.

<li><p>
Expressions in CREATE INDEX statements
may contain function calls, but only to functions whose output
is always determined completely by its input parameters (a.k.a.:
"deterministic" functions).  Obviously, functions like [random()] will not
work well in an index.  But also functions like [sqlite_version()], though
they are constant across any one database connection, are not constant
across the life of the underlying database file, and hence may not be
used in a CREATE INDEX statement.

page according to the 
needs and proclivities of the underlying system.  The unix and win32
[VFS] implementations that come built into SQLite do not write to the
lock-byte page, but third-party VFS implementations for
other operating systems might.</p>

<p>The lock-byte page arose from the need to support Win95 which had
only mandatory file locking.  All modern operating systems that we know of
support advisory file locking, and so the lock-byte page is not really
needed any more, but is retained for backwards compatibility.</p>

<tcl>hd_fragment {freelist} {freelist} {free-page list}</tcl>
<h2>The Freelist</h2>

<p>A database file might contain one or more pages that are not in

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_14.html">Version 3.14.0</a>
of SQLite is recommended for all new development.
</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>

  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}

newsitem {2016-08-08} {Release 3.14} {
SQLite [version 3.14] (the "&#960;" release)
is a regularly scheduled maintenance
release containing performance enhancements, new features, and fixes for
obscure bugs.
}

newsitem {2016-05-18} {Release 3.13.0} {
SQLite [version 3.13.0] is a regularly schedule maintenance release containing
performance enhancements and fixes for obscure bugs.
}

newsitem {2016-04-18} {Release 3.12.2} {
<p>Yikes!  The 3.12.0 and 3.12.1 releases contain a backwards compatibility bug!
   Tables that declare a column with type <tt>"INTEGER" PRIMARY KEY</tt>
   (where the datatype name INTEGER is quoted) generate an incompatible

<p>SQLite [version 3.9.2] is a patch release fixing two obscure bugs.
(Details: [https://www.sqlite.org/src/tktview?name=8a2adec166|(1)],
[https://www.sqlite.org/src/tktview?name=ac661962a2|(2)]).
Upgrade only if you are having problems.
}

newsitem {2015-10-16} {Release 3.9.1} {
<p>SQLite [version 3.9.1] is a
[https://www.sqlite.org/src/vpatch?from=version-3.9.0&to=version-3.9.1|small patch]
to [version 3.9.0] that includes
a few simple build script and #ifdef tweaks to make the code easier to 
compile on a wider variety of platform.  There are no functional changes, 
except for a single
[https://www.sqlite.org/src/info/57eec374ae1d0a1d4a|minor bug-fix] in 
[the json1 extension] to stop it from recognizing form-feed 

The total amount of data written is around three times the size of the
final database file. By contrast, an RBU Vacuum requires roughly the size
of the final database file in temporary disk space and writes a total of
twice that to disk.

<p>On the other hand, an RBU Vacuum uses more CPU than a regular SQLite
VACUUM - in one test as much as five times as much. For this reason, an RBU
Vaccum is often signficantly slower than an SQLite VACUUM under the same
conditions.

<li><b>RBU runs in the background</b>

<p>An ongoing RBU operation (either an update or a vacuum) does not
interfere with read access to the database file.

    }
  }
  rc = sqlite3rbu_close(pRbu);
  return rc;
}

}</tcl>

<p>A "rowid table" is any table in an SQLite schema that
<ul>
<li>is <em>not</em> a [virtual table], and
<li>is <em>not</em> a [WITHOUT ROWID] table.
</ul>
Most tables in a typical SQLite database schema are rowid tables.

<p>Rowid tables are distinguished by the fact that they all have
a unique, non-NULL, signed 64-bit integer [rowid] that is used as
the access key for the data in the underlying [B-tree] storage engine.

<h2>2.0 Quirks</h2>

<ul>
<li><p>

<p>This document is an introduction to the session extension.
The details of the interface are in the separate
[Session Extension C-language Interface] document.

<h3>1.1 Typical Use Case</h3>

<p>Suppose SQLite is used as the [application file format] for a
particular design application.  Two users, Alice and Bob, each start
with a baseline design that is about a gigabyte in size.  They work
all day, in parallel, each making their own customizations and tweaks
to the design.  At the end of the day, they would like to merge their
changes together into a single unified design.

<p>The session extension facilitates this by recording all changes to

<ul>
<li><b>alignment</b><i>N</i><b>.rc</b> - 
    These files contain -D options to the compiler that are used by
    various notable downstreams.
<li><b>cov.rc</b> - Options for measuring test coverage
<li><b>extensions.rc</b> - Options to enable [FTS4], [R-Trees],
    and [SQLITE_STAT4|STAT4].
<li><b>fast.rc</b> - Run most tests, including those not needed for
    coverage, skipping only soak tests, using delivery compiler options
    (ex: -O3)
<li><b>memdebug.rc</b> - like test.rc but also enable
    [SQLITE_MEMDEBUG|-DSQLITE_MEMDEBUG].
<li><b>min.rc</b> - Run the minimum set of tests needed for 100% coverage.
<li><b>quick.rc</b> - Run all tests required for 100% coverage tests
    using -Os and [SQLITE_DEBUG|-DSQLITE_DEBUG].

<blockquote><pre>
# Everything goes in a private namespace
namespace eval ::undo {

# proc:  ::undo::activate TABLE ...
# title: Start up the undo/redo system
#
# Arguments should be one or more database tables (in the database associated
# with the handle "db") whose changes are to be recorded for undo/redo
# purposes.
#
proc activate {args} {
  variable _undo
  if {$_undo(active)} return
  eval _create_triggers db $args