Documentation Source Text

  Enable the code the implements the [RBU extension].
}

COMPILE_OPTION {SQLITE_ENABLE_RTREE} {
  This option causes SQLite to include support for the
  [rtree | R*Tree index extension].
}

COMPILE_OPTION {SQLITE_ENABLE_SESSION} {
  This option enables the [session extension].
}

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.
}

  }
  hd_putsnl {</tr></table>}
}

hd_open_aux session/intro.html
hd_header Introduction
hd_enable_main 0
hd_keywords *session-capi {Session Extension C-language Interface}
</tcl>

<p>These pages define the C-language interface for the SQLite 
[session extension].
This is not a tutorial. These pages are designed to be precise, not
easy to read.  A tutorial is [session|available separately].


<p>This version of the C-language interface reference is
broken down into small pages for easy viewing.  The
same content is also available as a
<a href="../session.html">single large HTML file</a>
for those who prefer that format.</p>

</ol>

<tcl>
hd_close_aux
hd_enable_main 1
</tcl>

<p>This page defines the C-language interface to the SQLite 
   [session extension].
   This is not a tutorial. These pages are designed to be precise, not easy 
   to read.  A tutorial is [session extension|available separately].


<p>This page contains all C-language interface information
in a single HTML file.  The same information is also
available broken out into <a href="session/intro.html">lots of small pages</a>
for easier viewing, if you prefer.</p>

<p>This document is created by a script which scans comments in the source 

<title>The Session Extension</title>
<tcl>
hd_keywords {session} {session extension}
</tcl>
<h1 align="center">The Session Extension</h1>

<h2>1.0 Introduction</h2>

<p>The session extension provide a mechanism for recording changes
to some or all of the [rowid tables] in an SQLite database, and packaging
those changes into a "changeset" or "patchset" file that can later
be used to apply the same set of changes to another database with
the same schema and compatible starting data.  A "changeset" may
also be inverted and used to "undo" a session.

<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 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
both Alice's and Bob's databases and writing those changes into
changeset or patchset files.  At the end of the day, Alice can send her
changeset to Bob and Bob can "apply" it to his database.  The result (assuming
there are no conflicts) is that Bob's database then contains both his
changes and Alice's chanages.  Likewise, Bob can send a changeset of
his work over to Alice and she can apply his changes to her database.

<p>In other words, the session extension provides a facility for
SQLite database files that is similar to the unix
[https://en.wikipedia.org/wiki/Patch_(Unix)|patch] utility program,
or to the "merge" capabilities of version control systems such
as [https://www.fossil-scm.org/|Fossil], [http:git-scm.com|Git], 
or [http://www.mercurial-scm.org/|Mercurial].

<h3>1.2 Requirements And Limitations</h3>

<ul>
<li><p>
The session extension requires the [SQLITE_ENABLE_PREUPDATE_HOOK]
compile-time option to enable the preupdate hook interfaces.

<li><p>
All of the session extension code is omitted from the build unless
the [SQLITE_ENABLE_SESSION] compile-time option is used.

<li><p>
The session extension only works with [rowid tables].  Changes to
[WITHOUT ROWID] tables and [virtual tables] are not captured.
</ul>

<h2>2.0 Using The Session Extension</h2>

<i>TBD...</i>