Documentation Source Text

Artifact Content

Artifact 2ebfc5e0b1977cb8b8550922f6dcfbc4f0cc4a38:

<title>The Session Extension</title>
hd_keywords {session} {session extension}
<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 changes.  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
[|patch] utility program,
or to the "merge" capabilities of version control systems such
as [|Fossil], [|Git], 
or [|Mercurial].

<h3>1.2 Requirements And Limitations</h3>

The session extension requires the [SQLITE_ENABLE_PREUPDATE_HOOK]
compile-time option to enable the preupdate hook interfaces.

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

The session extension only works with [rowid tables].  Changes to
[WITHOUT ROWID] tables and [virtual tables] are not captured.

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