Debian Codegraph @

www/sessionintro.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>The Session Extension</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 The Session Extension
122 </div>
123 <details class="fancy_toc">
124 <summary>Table Of Contents</summary>
125 <div id="toc_sub"><div class="fancy-toc1"><a href="#introduction">1. Introduction</a></div>
126 <div class="fancy-toc2"><a href="#typical_use_case">1.1. Typical Use Case</a></div>
127 <div class="fancy-toc2"><a href="#obtaining_the_session_extension">1.2. Obtaining the Session Extension</a></div>
128 <div class="fancy-toc2"><a href="#limitations">1.3. Limitations</a></div>
129 <div class="fancy-toc1"><a href="#concepts">2. Concepts</a></div>
130 <div class="fancy-toc2"><a href="#changesets_and_patchsets">2.1. Changesets and Patchsets</a></div>
131 <div class="fancy-toc2"><a href="#conflicts">2.2. Conflicts</a></div>
132 <div class="fancy-toc2"><a href="#changeset_construction">2.3. Changeset Construction</a></div>
133 <div class="fancy-toc1"><a href="#using_the_session_extension">3. Using The Session Extension</a></div>
134 <div class="fancy-toc2"><a href="#capturing_a_changeset">3.1. Capturing a Changeset</a></div>
135 <div class="fancy-toc2"><a href="#applying_a_changeset_to_a_database">3.2. Applying a Changeset to a Database</a></div>
136 <div class="fancy-toc2"><a href="#inspecting_the_contents_of_a_changeset">3.3. Inspecting the Contents of a Changeset</a></div>
137 <div class="fancy-toc1"><a href="#extended_functionality">4. Extended Functionality</a></div>
138 </div>
139 </details>
140 </div>
141
142
143
144
145
146 <h1 id="introduction"><span>1. </span>Introduction</h1>
147
148 <p>The session extension provides a convenient mechanism to record
149 changes to tables in an SQLite database, package those changes into
150 a "changeset" or "patchset" file, and later apply the same set of
151 changes to another database with the same schema and compatible
152 starting data. A "changeset" may also be inverted and used to
153 "undo" a session.</p>
154
155 <p>This document is an introduction to the session extension.
156 The details of the interface are in the separate
157 <a href="session/intro.html">Session Extension C-language Interface</a> document.
158
159 </p><h2 id="typical_use_case"><span>1.1. </span>Typical Use Case</h2>
160
161 <p>Suppose SQLite is used as the <a href="appfileformat.html">application file format</a> for a
162 particular design application. Two users, Alice and Bob, each start
163 with a baseline design that is about a gigabyte in size. They work
164 all day, in parallel, each making their own customizations and tweaks
165 to the design. At the end of the day, they would like to merge their
166 changes together into a single unified design.
167
168 </p><p>The session extension facilitates this by recording all changes to
169 both Alice's and Bob's databases and writing those changes into
170 changeset or patchset files. At the end of the day, Alice can send her
171 changeset to Bob and Bob can "apply" it to his database. The result (assuming
172 there are no conflicts) is that Bob's database then contains both his
173 changes and Alice's changes. Likewise, Bob can send a changeset of
174 his work over to Alice and she can apply his changes to her database.
175
176 </p><p>In other words, the session extension provides a facility for
177 SQLite database files that is similar to the unix
178 <a href="https://en.wikipedia.org/wiki/Patch_(Unix)">patch</a> utility program,
179 or to the "merge" capabilities of version control systems such
180 as <a href="https://www.fossil-scm.org/">Fossil</a>, <a href="https://git-scm.com">Git</a>,
181 or <a href="http://www.mercurial-scm.org/">Mercurial</a>.
182
183 </p><h2 id="obtaining_the_session_extension"><span>1.2. </span>Obtaining the Session Extension</h2>
184
185 <p> Since <a href="releaselog/3_13_0.html">version 3.13.0</a> (2016-05-18),
186 the session extension has been included in the SQLite
187 <a href="amalgamation.html">amalgamation</a> source distribution. By default, the session extension is
188 disabled. To enable it, build with the following compiler switches:
189
190 </p><div class="codeblock"><pre>-DSQLITE_ENABLE_SESSION -DSQLITE_ENABLE_PREUPDATE_HOOK
191 </pre></div>
192
193 <p> Or, if using the canonical build system,
194 pass the --enable-session option to the configure script.
195
196 </p><h2 id="limitations"><span>1.3. </span>Limitations</h2>
197
198 <ul>
199
200 <li><p> Prior to SQLite version 3.17.0, the session extension only worked with
201 <a href="rowidtable.html">rowid tables</a>, not <a href="withoutrowid.html">WITHOUT ROWID</a> tables. As of 3.17.0, both
202 rowid and WITHOUT ROWID tables are supported. However, extra steps are
203 needed to record primary keys for WITHOUT ROWID table changes.
204
205 </p></li><li><p> There is no support for <a href="vtab.html">virtual tables</a>. Changes to virtual tables are
206 not captured.
207
208 </p></li><li><p> The session extension only works with tables that have a declared
209 PRIMARY KEY. The PRIMARY KEY of a table may be an INTEGER PRIMARY KEY
210 (rowid alias) or an external PRIMARY KEY.
211
212 </p></li><li><p> SQLite allows <a href="nulls.html">NULL values</a> to be stored in
213 PRIMARY KEY columns. However, the session extension ignores all
214 such rows. No changes affecting rows with one or more NULL values
215 in PRIMARY KEY columns are recorded by the sessions module.
216 </p></li></ul>
217
218 <h1 id="concepts"><span>2. </span>Concepts</h1>
219
220 <a name="changeset"></a>
221
222 <h2 id="changesets_and_patchsets"><span>2.1. </span>Changesets and Patchsets</h2>
223 <p> The sessions module revolves around creating and manipulating
224 changesets. A changeset is a blob of data that encodes a series of
225 changes to a database. Each change in a changeset is one of the
226 following:
227
228 </p><ul>
229 <li> <p>An <b>INSERT</b>. An INSERT change contains a single row to add to
230 a database table. The payload of the INSERT change consists of the
231 values for each field of the new row.
232
233 </p></li><li> <p>A <b>DELETE</b>. A DELETE change represents a row, identified by
234 its primary key values, to remove from a database table. The payload
235 of a DELETE change consists of the values for all fields of the
236 deleted row.
237
238 </p></li><li> <p>An <b>UPDATE</b>. An UPDATE change represents the modification of
239 one or more non-PRIMARY KEY fields of a single row within a database
240 table, identified by its PRIMARY KEY fields. The payload for an UPDATE
241 change consists of:
242 </p><ul>
243 <li> The PRIMARY KEY values identifying the modified row,
244 </li><li> The new values for each modified field of the row, and
245 </li><li> The original values for each modified field of the row.
246 </li></ul>
247 <p> An UPDATE change does not contain any information regarding
248 non-PRIMARY KEY fields that are not modified by the change. It is not
249 possible for an UPDATE change to specify modifications to PRIMARY
250 KEY fields.
251 </p></li></ul>
252
253 <p> A single changeset may contain changes that apply to more than one
254 database table. For each table that the changeset includes at least one change
255 for, it also encodes the following data:
256
257 </p><ul>
258 <li> The name of the database table,
259 </li><li> The number of columns the table has, and
260 </li><li> Which of those columns are PRIMARY KEY columns.
261 </li></ul>
262
263 <p> Changesets may only be applied to databases that contain tables
264 matching the above three criteria as stored in the changeset.
265
266 </p><p> A patchset is similar to a changeset. It is slightly more compact than
267 a changeset, but provides more limited conflict detection and resolution
268 options (see the next section for details). The differences between a
269 patchset and a changeset are that:
270
271 </p><ul>
272 <li><p> For a <b>DELETE</b> change, the payload consists of the PRIMARY KEY
273 fields only. The original values of other fields are not stored as
274 part of a patchset.
275
276 </p></li><li><p> For an <b>UPDATE</b> change, the payload consists of the PRIMARY KEY
277 fields and the new values of modified fields only. The original
278 values of modified fields are not stored as part of a patchset.
279 </p></li></ul>
280
281 <h2 id="conflicts"><span>2.2. </span>Conflicts</h2>
282
283 <p> When a changeset or patchset is applied to a database, an attempt is
284 made to insert a new row for each INSERT change, remove a row for each
285 DELETE change and modify a row for each UPDATE change. If the target
286 database is in the same state as the original database that the changeset
287 was recorded on, this is a simple matter. However, if the contents of the
288 target database is not in exactly this state, conflicts can occur when
289 applying the changeset or patchset.
290
291 </p><p>When processing an <b>INSERT</b> change, the following conflicts can
292 occur:
293
294 </p><ul>
295 <li> The target database may already contain a row with the same PRIMARY
296 KEY values as specified by the INSERT change.
297
298 </li><li> Some other database constraint, for example a UNIQUE or CHECK
299 constraint, may be violated when the new row is inserted.
300 </li></ul>
301
302 <p>When processing a <b>DELETE</b> change, the following conflicts may be
303 detected:
304
305 </p><ul>
306 <li> The target database may contain no row with the specified PRIMARY
307 KEY values to delete.
308
309 </li><li> The target database may contain a row with the specified PRIMARY
310 KEY values, but the other fields may contain values that do not
311 match those stored as part of the changeset. This type of conflict
312 is not detected when using a patchset.
313 </li></ul>
314
315 <p>When processing an <b>UPDATE</b> change, the following conflicts may be
316 detected:
317
318 </p><ul>
319 <li> The target database may contain no row with the specified PRIMARY
320 KEY values to modify.
321
322 </li><li> The target database may contain a row with the specified PRIMARY
323 KEY values, but the current values of the fields that will be modified
324 by the change may not match the original values stored within the
325 changeset. This type of conflict is not detected when using a patchset.
326
327 </li><li> Some other database constraint, for example a UNIQUE or CHECK
328 constraint, may be violated when the row is updated.
329 </li></ul>
330
331 <p> Depending on the type of conflict, a sessions application has a variety
332 of configurable options for dealing with conflicts, ranging from omitting the
333 conflicting change, aborting the entire changeset application or applying
334 the change despite the conflict. For details, refer to the documentation for
335 the <a href="session/sqlite3changeset_apply.html">sqlite3changeset_apply()</a> API.
336
337 </p><h2 id="changeset_construction"><span>2.3. </span>Changeset Construction</h2>
338
339 <p> After a session object has been configured, it begins monitoring for
340 changes to its configured tables. However, it does not record an entire
341 change each time a row within the database is modified. Instead, it records
342 just the PRIMARY KEY fields for each inserted row, and just the PRIMARY KEY
343 and all original row values for any updated or deleted rows. If a row is
344 modified more than once by a single session, no new information is recorded.
345
346 </p><p> The other information required to create a changeset or patchset is
347 read from the database file when <a href="session/sqlite3session_changeset.html">sqlite3session_changeset()</a> or
348 <a href="session/sqlite3session_patchset.html">sqlite3session_patchset()</a> is called. Specifically,
349
350 </p><ul>
351 <li> <p>For each primary key recorded as a result of an INSERT operation,
352 the sessions module checks if there is a row with a matching primary
353 key still in the table. If so, an INSERT change is added to the
354 changeset.
355
356 </p></li><li> <p>For each primary key recorded as a result of an UPDATE or DELETE
357 operation, the sessions module also checks for a row with a matching
358 primary key within the table. If one can be found, but one or more
359 of the non-PRIMARY KEY fields does not match the original recorded
360 value, an UPDATE is added to the changeset. Or, if there is no row
361 at all with the specified primary key, a DELETE is added to the
362 changeset. If the row does exist but none of the non-PRIMARY KEY
363 fields have been modified, no change is added to the changeset.
364 </p></li></ul>
365
366 <p> One implication of the above is that if a change is made and then
367 unmade within a single session (for example if a row is inserted and then
368 deleted again), the sessions module does not report any change at all. Or
369 if a row is updated multiple times within the same session, all updates
370 are coalesced into a single update within any changeset or patchset blob.
371
372 </p><h1 id="using_the_session_extension"><span>3. </span>Using The Session Extension</h1>
373
374 <p> This section provides examples that demonstrate how to use the session
375 extension.
376
377 </p><h2 id="capturing_a_changeset"><span>3.1. </span>Capturing a Changeset</h2>
378
379 <p> The example code below demonstrates the steps involved in capturing a
380 changeset while executing SQL commands. In summary:
381
382 </p><ol>
383 <li> <p>A session object (type sqlite3_session*) is created by making a
384 call to the <a href="session/sqlite3session_create.html">sqlite3session_create()</a> API function.
385
386 </p><p>A single session object monitors changes made to a single database
387 (i.e. "main", "temp" or an attached database) via a single
388 sqlite3* database handle.
389
390 </p></li><li> <p>The session object is configured with a set of tables to monitor
391 changes on.
392
393 </p><p> By default a session object does not monitor changes on any
394 database table. Before it does so it must be configured. There
395 are three ways to configure the set of tables to monitor changes
396 on:
397 </p><ul>
398 <li> By explicitly specifying tables using one call to
399 <a href="session/sqlite3session_attach.html">sqlite3session_attach()</a> for each table, or
400
401 </li><li> By specifying that all tables in the database should be monitored
402 for changes using a call to <a href="session/sqlite3session_attach.html">sqlite3session_attach()</a> with a
403 NULL argument, or
404
405 </li><li> By configuring a callback to be invoked the first time each table
406 is written to that indicates to the session module whether or
407 not changes on the table should be monitored.
408 </li></ul>
409 <p> The example code below uses the second of the methods enumerated
410 above - it monitors for changes on all database tables.
411
412 </p></li><li> <p> Changes are made to the database by executing SQL statements. The
413 session object records these changes.
414
415 </p></li><li> <p> A changeset blob is extracted from the session object using a call
416 to <a href="session/sqlite3session_changeset.html">sqlite3session_changeset()</a> (or, if using patchsets, a call to
417 the <a href="session/sqlite3session_patchset.html">sqlite3session_patchset()</a> function).
418
419 </p></li><li> <p> The session object is deleted using a call to the
420 <a href="session/sqlite3session_delete.html">sqlite3session_delete()</a> API function.
421
422 </p><p> It is not necessary to delete a session object after extracting
423 a changeset or patchset from it. It can be left attached to the
424 database handle and will continue monitoring for changes on the
425 configured tables as before. However, if
426 <a href="session/sqlite3session_changeset.html">sqlite3session_changeset()</a> or <a href="session/sqlite3session_patchset.html">sqlite3session_patchset()</a> is
427 called a second time on a session object, the changeset or patchset
428 will contain <em>all</em> changes that have taken place on the connection
429 since the session was created. In other words,
430 a session object is not reset or
431 zeroed by a call to sqlite3session_changeset() or
432 sqlite3session_patchset().
433 </p></li></ol>
434
435 <div class="codeblock"><pre><i>/*
436 ** Argument zSql points to a buffer containing an SQL script to execute
437 ** against the database handle passed as the first argument. As well as
438 ** executing the SQL script, this function collects a changeset recording
439 ** all changes made to the "main" database file. Assuming no error occurs,
440 ** output variables (*ppChangeset) and (*pnChangeset) are set to point
441 ** to a buffer containing the changeset and the size of the changeset in
442 ** bytes before returning SQLITE_OK. In this case it is the responsibility
443 ** of the caller to eventually free the changeset blob by passing it to
444 ** the sqlite3_free function.
445 **
446 ** Or, if an error does occur, return an SQLite error code. The final
447 ** value of (*pChangeset) and (*pnChangeset) are undefined in this case.
448 */</i>
449 int sql_exec_changeset(
450 sqlite3 *db, <i>/* Database handle */</i>
451 const char *zSql, <i>/* SQL script to execute */</i>
452 int *pnChangeset, <i>/* OUT: Size of changeset blob in bytes */</i>
453 void **ppChangeset <i>/* OUT: Pointer to changeset blob */</i>
454 ){
455 sqlite3_session *pSession = 0;
456 int rc;
457
458 <i>/* Create a new session object */</i>
459 rc = sqlite3session_create(db, "main", &pSession);
460
461 <i>/* Configure the session object to record changes to all tables */</i>
462 if( rc==SQLITE_OK ) rc = sqlite3session_attach(pSession, NULL);
463
464 <i>/* Execute the SQL script */</i>
465 if( rc==SQLITE_OK ) rc = sqlite3_exec(db, zSql, 0, 0, 0);
466
467 <i>/* Collect the changeset */</i>
468 if( rc==SQLITE_OK ){
469 rc = sqlite3session_changeset(pSession, pnChangeset, ppChangeset);
470 }
471
472 <i>/* Delete the session object */</i>
473 sqlite3session_delete(pSession);
474
475 return rc;
476 }
477 </pre></div>
478
479 <h2 id="applying_a_changeset_to_a_database"><span>3.2. </span>Applying a Changeset to a Database</h2>
480
481 <p> Applying a changeset to a database is simpler than capturing a changeset.
482 Usually, a single call to <a href="session/sqlite3changeset_apply.html">sqlite3changeset_apply()</a>, as depicted in the
483 example code below, suffices.
484
485 </p><p> In cases where it is complicated, the complications in applying a
486 changeset lie in conflict resolution. Refer to the API documentation linked
487 above for details.
488
489 </p><div class="codeblock"><pre><i>/*
490 ** Conflict handler callback used by apply_changeset(). See below.
491 */</i>
492 static int xConflict(void *pCtx, int eConflict, sqlite3_changeset_iter *pIter){
493 int ret = (int)pCtx;
494 return ret;
495 }
496
497 <i>/*
498 ** Apply the changeset contained in blob pChangeset, size nChangeset bytes,
499 ** to the main database of the database handle passed as the first argument.
500 ** Return SQLITE_OK if successful, or an SQLite error code if an error
501 ** occurs.
502 **
503 ** If parameter bIgnoreConflicts is true, then any conflicting changes
504 ** within the changeset are simply ignored. Or, if bIgnoreConflicts is
505 ** false, then this call fails with an SQLITE_ABORT error if a changeset
506 ** conflict is encountered.
507 */</i>
508 int apply_changeset(
509 sqlite3 *db, <i>/* Database handle */</i>
510 int bIgnoreConflicts, <i>/* True to ignore conflicting changes */</i>
511 int nChangeset, <i>/* Size of changeset in bytes */</i>
512 void *pChangeset <i>/* Pointer to changeset blob */</i>
513 ){
514 return sqlite3changeset_apply(
515 db,
516 nChangeset, pChangeset,
517 0, xConflict,
518 (void*)bIgnoreConflicts
519 );
520 }
521 </pre></div>
522
523 <h2 id="inspecting_the_contents_of_a_changeset"><span>3.3. </span>Inspecting the Contents of a Changeset</h2>
524
525 <p> The example code below demonstrates the techniques used to iterate
526 through and extract the data related to all changes in a changeset. To
527 summarize:
528
529 </p><ol>
530 <li><p> The <a href="session/sqlite3changeset_start.html">sqlite3changeset_start()</a> API is called to create and
531 initialize an iterator to iterate through the contents of a
532 changeset. Initially, the iterator points to no element at all.
533
534 </p></li><li><p> The first call to <a href="session/sqlite3changeset_next.html">sqlite3changeset_next()</a> on the iterator moves
535 it to point to the first change in the changeset (or to EOF, if
536 the changeset is completely empty). sqlite3changeset_next() returns
537 SQLITE_ROW if it moves the iterator to point to a valid entry,
538 SQLITE_DONE if it moves the iterator to EOF, or an SQLite error
539 code if an error occurs.
540
541 </p></li><li><p> If the iterator points to a valid entry, the <a href="session/sqlite3changeset_op.html">sqlite3changeset_op()</a>
542 API may be used to determine the type of change (INSERT, UPDATE or
543 DELETE) that the iterator points to. Additionally, the same API
544 can be used to obtain the name of the table the change applies to
545 and its expected number of columns and primary key columns.
546
547 </p></li><li><p> If the iterator points to a valid INSERT or UPDATE entry, the
548 <a href="session/sqlite3changeset_new.html">sqlite3changeset_new()</a> API may be used to obtain the new.* values
549 within the change payload.
550
551 </p></li><li><p> If the iterator points to a valid DELETE or UPDATE entry, the
552 <a href="session/sqlite3changeset_old.html">sqlite3changeset_old()</a> API may be used to obtain the old.* values
553 within the change payload.
554
555 </p></li><li><p> An iterator is deleted using a call to the
556 <a href="session/sqlite3changeset_finalize.html">sqlite3changeset_finalize()</a> API. If an error occurred while
557 iterating, an SQLite error code is returned (even if the same error
558 code has already been returned by sqlite3changeset_next()). Or,
559 if no error has occurred, SQLITE_OK is returned.
560 </p></li></ol>
561
562 <div class="codeblock"><pre><i>/*
563 ** Print the contents of the changeset to stdout.
564 */</i>
565 static int print_changeset(void *pChangeset, int nChangeset){
566 int rc;
567 sqlite3_changeset_iter *pIter = 0;
568
569 <i>/* Create an iterator to iterate through the changeset */</i>
570 rc = sqlite3changeset_start(&pIter, nChangeset, pChangeset);
571 if( rc!=SQLITE_OK ) return rc;
572
573 <i>/* This loop runs once for each change in the changeset */</i>
574 while( SQLITE_ROW==sqlite3changeset_next(pIter) ){
575 const char *zTab; <i>/* Table change applies to */</i>
576 int nCol; <i>/* Number of columns in table zTab */</i>
577 int op; <i>/* SQLITE_INSERT, UPDATE or DELETE */</i>
578 sqlite3_value *pVal;
579
580 <i>/* Print the type of operation and the table it is on */</i>
581 rc = sqlite3changeset_op(pIter, &zTab, &nCol, &op, 0);
582 if( rc!=SQLITE_OK ) goto exit_print_changeset;
583 printf("%s on table %s\n",
584 op==SQLITE_INSERT?"INSERT" : op==SQLITE_UPDATE?"UPDATE" : "DELETE",
585 zTab
586 );
587
588 <i>/* If this is an UPDATE or DELETE, print the old.* values */</i>
589 if( op==SQLITE_UPDATE || op==SQLITE_DELETE ){
590 printf("Old values:");
591 for(i=0; i&lt;nCol; i++){
592 rc = sqlite3changeset_old(pIter, i, &pVal);
593 if( rc!=SQLITE_OK ) goto exit_print_changeset;
594 printf(" %s", pVal ? sqlite3_value_text(pVal) : "-");
595 }
596 printf("\n");
597 }
598
599 <i>/* If this is an UPDATE or INSERT, print the new.* values */</i>
600 if( op==SQLITE_UPDATE || op==SQLITE_INSERT ){
601 printf("New values:");
602 for(i=0; i&lt;nCol; i++){
603 rc = sqlite3changeset_new(pIter, i, &pVal);
604 if( rc!=SQLITE_OK ) goto exit_print_changeset;
605 printf(" %s", pVal ? sqlite3_value_text(pVal) : "-");
606 }
607 printf("\n");
608 }
609 }
610
611 <i>/* Clean up the changeset and return an error code (or SQLITE_OK) */</i>
612 exit_print_changeset:
613 rc2 = sqlite3changeset_finalize(pIter);
614 if( rc==SQLITE_OK ) rc = rc2;
615 return rc;
616 }
617 </pre></div>
618
619 <h1 id="extended_functionality"><span>4. </span>Extended Functionality</h1>
620
621 <p> Most applications will only use the session module functionality described
622 in the previous section. However, the following additional functionality is
623 available for the use and manipulation of changeset and patchset blobs:
624
625 </p><ul>
626 <li> <p>Two or more changeset/patchsets may be combined using the
627 <a href="session/sqlite3changeset_concat.html">sqlite3changeset_concat()</a> or <a href="session/changegroup.html">sqlite3_changegroup</a> interfaces.
628
629 </p></li><li> <p>A changeset may be "inverted" using the <a href="session/sqlite3changeset_invert.html">sqlite3changeset_invert()</a>
630 API function. An inverted changeset undoes the changes made by the
631 original. If changeset C<sup>+</sup> is the inverse of changeset C, then
632 applying C and then C<sup>+</sup> to a database should leave
633 the database unchanged.
634 </p></li></ul>
635 <p align="center"><small><i>This page was last updated on 2025-05-31 13:08:22Z </small></i></p>
636