Documentation Source Text

Check-in [24e5940ece]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Create a place-holder for a tutorial on the session extension.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 24e5940ece0b95f297580178b81b7bf7e5ff89b2
User & Date: drh 2016-04-01 16:08:58
Context
2016-04-04
12:24
Typo fixes from Johannes Laire on unreleased documents. check-in: e3943543c8 user: drh tags: trunk
2016-04-01
16:08
Create a place-holder for a tutorial on the session extension. check-in: 24e5940ece user: drh tags: trunk
14:57
Merge changes from the 3.12.0 branch. Add the "rowidtable.html" page. Add documentation for SQLITE_ENABLE_PREUPDATE_HOOK. check-in: 74e8dbd8bf user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/compile.in.

813
814
815
816
817
818
819




820
821
822
823
824
825
826
  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_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.
}







>
>
>
>







813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
  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.
}

Changes to pages/session.in.

225
226
227
228
229
230
231
232
233
234
235

236
237
238
239
240
241
242
243
244
245
...
267
268
269
270
271
272
273
274

275
276
277
278
279
280
281
282
283
284
  }
  hd_putsnl {</tr></table>}
}

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

<p>These pages define the C-language interface for the SQLite session

module. This is not a tutorial. These pages are designed to be precise, not
easy to read. Unfortunately, there is currently no tutorial introduction to
the session module.

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

   This is not a tutorial. These pages are designed to be precise, not easy 
   to read. Unfortunately, there is currently no tutorial introduction to
   the session module.

<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 







|


|
>
|
<
|







 







|
>

<
|







225
226
227
228
229
230
231
232
233
234
235
236
237

238
239
240
241
242
243
244
245
...
267
268
269
270
271
272
273
274
275
276

277
278
279
280
281
282
283
284
  }
  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 

Added pages/sessionintro.in.





























































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
<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>