Debian Codegraph @

www/session/sqlite3changeset_apply.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>Apply A Changeset To A Database</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 <a href="../session/intro.html"><h2>Session Module C Interface</h2></a><h2>Apply A Changeset To A Database</h2><blockquote><pre>int sqlite3changeset_apply(
119 sqlite3 *db, /* Apply change to "main" db of this handle */
120 int nChangeset, /* Size of changeset in bytes */
121 void *pChangeset, /* Changeset blob */
122 int(*xFilter)(
123 void *pCtx, /* Copy of sixth arg to _apply() */
124 const char *zTab /* Table name */
125 ),
126 int(*xConflict)(
127 void *pCtx, /* Copy of sixth arg to _apply() */
128 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
129 sqlite3_changeset_iter *p /* Handle describing change and conflict */
130 ),
131 void *pCtx /* First argument passed to xConflict */
132 );
133 int sqlite3changeset_apply_v2(
134 sqlite3 *db, /* Apply change to "main" db of this handle */
135 int nChangeset, /* Size of changeset in bytes */
136 void *pChangeset, /* Changeset blob */
137 int(*xFilter)(
138 void *pCtx, /* Copy of sixth arg to _apply() */
139 const char *zTab /* Table name */
140 ),
141 int(*xConflict)(
142 void *pCtx, /* Copy of sixth arg to _apply() */
143 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
144 sqlite3_changeset_iter *p /* Handle describing change and conflict */
145 ),
146 void *pCtx, /* First argument passed to xConflict */
147 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
148 int flags /* SESSION_CHANGESETAPPLY_* flags */
149 );
150 int sqlite3changeset_apply_v3(
151 sqlite3 *db, /* Apply change to "main" db of this handle */
152 int nChangeset, /* Size of changeset in bytes */
153 void *pChangeset, /* Changeset blob */
154 int(*xFilter)(
155 void *pCtx, /* Copy of sixth arg to _apply() */
156 sqlite3_changeset_iter *p /* Handle describing change */
157 ),
158 int(*xConflict)(
159 void *pCtx, /* Copy of sixth arg to _apply() */
160 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
161 sqlite3_changeset_iter *p /* Handle describing change and conflict */
162 ),
163 void *pCtx, /* First argument passed to xConflict */
164 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
165 int flags /* SESSION_CHANGESETAPPLY_* flags */
166 );
167 </pre></blockquote><p>
168 Apply a changeset or patchset to a database. These functions attempt to
169 update the "main" database attached to handle db with the changes found in
170 the changeset passed via the second and third arguments. </p>
171
172 <p>All changes made by these functions are enclosed in a savepoint transaction.
173 If any other error (aside from a constraint failure when attempting to
174 write to the target database) occurs, then the savepoint transaction is
175 rolled back, restoring the target database to its original state, and an
176 SQLite error code returned. Additionally, starting with version 3.51.0,
177 an error code and error message that may be accessed using the
178 <a href="../c3ref/errcode.html">sqlite3_errcode()</a> and <a href="../c3ref/errcode.html">sqlite3_errmsg()</a> APIs are left in the database
179 handle.</p>
180
181 <p>The fourth argument (xFilter) passed to these functions is the "filter
182 callback". This may be passed NULL, in which case all changes in the
183 changeset are applied to the database. For sqlite3changeset_apply() and
184 sqlite3_changeset_apply_v2(), if it is not NULL, then it is invoked once
185 for each table affected by at least one change in the changeset. In this
186 case the table name is passed as the second argument, and a copy of
187 the context pointer passed as the sixth argument to apply() or apply_v2()
188 as the first. If the "filter callback" returns zero, then no attempt is
189 made to apply any changes to the table. Otherwise, if the return value is
190 non-zero, all changes related to the table are attempted.</p>
191
192 <p>For sqlite3_changeset_apply_v3(), the xFilter callback is invoked once
193 per change. The second argument in this case is an sqlite3_changeset_iter
194 that may be queried using the usual APIs for the details of the current
195 change. If the "filter callback" returns zero in this case, then no attempt
196 is made to apply the current change. If it returns non-zero, the change
197 is applied.</p>
198
199 <p>For each table that is not excluded by the filter callback, this function
200 tests that the target database contains a compatible table. A table is
201 considered compatible if all of the following are true:</p>
202
203 <p><ul>
204 <li> The table has the same name as the name recorded in the
205 changeset, and
206 <li> The table has at least as many columns as recorded in the
207 changeset, and
208 <li> The table has primary key columns in the same position as
209 recorded in the changeset.
210 </ul></p>
211
212 <p>If there is no compatible table, it is not an error, but none of the
213 changes associated with the table are applied. A warning message is issued
214 via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
215 one such warning is issued for each table in the changeset.</p>
216
217 <p>For each change for which there is a compatible table, an attempt is made
218 to modify the table contents according to each UPDATE, INSERT or DELETE
219 change that is not excluded by a filter callback. If a change cannot be
220 applied cleanly, the conflict handler function passed as the fifth argument
221 to sqlite3changeset_apply() may be invoked. A description of exactly when
222 the conflict handler is invoked for each type of change is below.</p>
223
224 <p>Unlike the xFilter argument, xConflict may not be passed NULL. The results
225 of passing anything other than a valid function pointer as the xConflict
226 argument are undefined.</p>
227
228 <p>Each time the conflict handler function is invoked, it must return one
229 of <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_OMIT</a>, <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_ABORT</a> or
230 <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_REPLACE</a>. SQLITE_CHANGESET_REPLACE may only be returned
231 if the second argument passed to the conflict handler is either
232 SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
233 returns an illegal value, any changes already made are rolled back and
234 the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
235 actions are taken by sqlite3changeset_apply() depending on the value
236 returned by each invocation of the conflict-handler function. Refer to
237 the documentation for the three
238 <a href="../session/c_changeset_abort.html">available return values</a> for details.</p>
239
240 <p><dl>
241 <dt>DELETE Changes<dd>
242 For each DELETE change, the function checks if the target database
243 contains a row with the same primary key value (or values) as the
244 original row values stored in the changeset. If it does, and the values
245 stored in all non-primary key columns also match the values stored in
246 the changeset the row is deleted from the target database.</p>
247
248 <p> If a row with matching primary key values is found, but one or more of
249 the non-primary key fields contains a value different from the original
250 row value stored in the changeset, the conflict-handler function is
251 invoked with <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_DATA</a> as the second argument. If the
252 database table has more columns than are recorded in the changeset,
253 only the values of those non-primary key fields are compared against
254 the current database contents - any trailing database table columns
255 are ignored.</p>
256
257 <p> If no row with matching primary key values is found in the database,
258 the conflict-handler function is invoked with <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_NOTFOUND</a>
259 passed as the second argument.</p>
260
261 <p> If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
262 (which can only happen if a foreign key constraint is violated), the
263 conflict-handler function is invoked with <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_CONSTRAINT</a>
264 passed as the second argument. This includes the case where the DELETE
265 operation is attempted because an earlier call to the conflict handler
266 function returned <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_REPLACE</a>.</p>
267
268 <p><dt>INSERT Changes<dd>
269 For each INSERT change, an attempt is made to insert the new row into
270 the database. If the changeset row contains fewer fields than the
271 database table, the trailing fields are populated with their default
272 values.</p>
273
274 <p> If the attempt to insert the row fails because the database already
275 contains a row with the same primary key values, the conflict handler
276 function is invoked with the second argument set to
277 <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_CONFLICT</a>.</p>
278
279 <p> If the attempt to insert the row fails because of some other constraint
280 violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
281 invoked with the second argument set to <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_CONSTRAINT</a>.
282 This includes the case where the INSERT operation is re-attempted because
283 an earlier call to the conflict handler function returned
284 <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_REPLACE</a>.</p>
285
286 <p><dt>UPDATE Changes<dd>
287 For each UPDATE change, the function checks if the target database
288 contains a row with the same primary key value (or values) as the
289 original row values stored in the changeset. If it does, and the values
290 stored in all modified non-primary key columns also match the values
291 stored in the changeset the row is updated within the target database.</p>
292
293 <p> If a row with matching primary key values is found, but one or more of
294 the modified non-primary key fields contains a value different from an
295 original row value stored in the changeset, the conflict-handler function
296 is invoked with <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_DATA</a> as the second argument. Since
297 UPDATE changes only contain values for non-primary key fields that are
298 to be modified, only those fields need to match the original values to
299 avoid the SQLITE_CHANGESET_DATA conflict-handler callback.</p>
300
301 <p> If no row with matching primary key values is found in the database,
302 the conflict-handler function is invoked with <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_NOTFOUND</a>
303 passed as the second argument.</p>
304
305 <p> If the UPDATE operation is attempted, but SQLite returns
306 SQLITE_CONSTRAINT, the conflict-handler function is invoked with
307 <a href="../session/c_changeset_conflict.html">SQLITE_CHANGESET_CONSTRAINT</a> passed as the second argument.
308 This includes the case where the UPDATE operation is attempted after
309 an earlier call to the conflict handler function returned
310 <a href="../session/c_changeset_abort.html">SQLITE_CHANGESET_REPLACE</a>.
311 </dl></p>
312
313 <p>It is safe to execute SQL statements, including those that write to the
314 table that the callback related to, from within the xConflict callback.
315 This can be used to further customize the application's conflict
316 resolution strategy.</p>
317
318 <p>If the output parameters (ppRebase) and (pnRebase) are non-NULL and
319 the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
320 may set (*ppRebase) to point to a "rebase" that may be used with the
321 sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
322 is set to the size of the buffer in bytes. It is the responsibility of the
323 caller to eventually free any such buffer using sqlite3_free(). The buffer
324 is only allocated and populated if one or more conflicts were encountered
325 while applying the patchset. See comments surrounding the sqlite3_rebaser
326 APIs for further details.</p>
327
328 <p>The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
329 may be modified by passing a combination of
330 <a href="../session/c_changesetapply_fknoaction.html">supported flags</a> as the 9th parameter.</p>
331
332 <p>Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
333 and therefore subject to change.
334 </p><p>See also lists of
335 <a href="../session/objlist.html">Objects</a>,
336 <a href="../session/constlist.html">Constants</a>, and
337 <a href="../session/funclist.html">Functions</a>.</p>
338