Debian Codegraph @

www/c3ref/backup_finish.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>Online Backup API.</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 <!-- keywords: sqlite3_backup_finish sqlite3_backup_init sqlite3_backup_pagecount sqlite3_backup_remaining sqlite3_backup_step -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Online Backup API.</h2>
122 </div>
123 <blockquote><pre>
124 sqlite3_backup *sqlite3_backup_init(
125 sqlite3 *pDest, /* Destination database handle */
126 const char *zDestName, /* Destination database name */
127 sqlite3 *pSource, /* Source database handle */
128 const char *zSourceName /* Source database name */
129 );
130 int sqlite3_backup_step(sqlite3_backup *p, int nPage);
131 int sqlite3_backup_finish(sqlite3_backup *p);
132 int sqlite3_backup_remaining(sqlite3_backup *p);
133 int sqlite3_backup_pagecount(sqlite3_backup *p);
134 </pre></blockquote>
135 <p>
136 The backup API copies the content of one database into another.
137 It is useful either for creating backups of databases or
138 for copying in-memory databases to or from persistent files.</p>
139
140 <p>See Also: <a href="../backup.html">Using the SQLite Online Backup API</a></p>
141
142 <p>SQLite holds a write transaction open on the destination database file
143 for the duration of the backup operation.
144 The source database is read-locked only while it is being read;
145 it is not locked continuously for the entire backup operation.
146 Thus, the backup may be performed on a live source database without
147 preventing other database connections from
148 reading or writing to the source database while the backup is underway.</p>
149
150 <p>To perform a backup operation:
151 <ol>
152 <li><b>sqlite3_backup_init()</b> is called once to initialize the
153 backup,
154 <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
155 the data between the two databases, and finally
156 <li><b>sqlite3_backup_finish()</b> is called to release all resources
157 associated with the backup operation.
158 </ol>
159 There should be exactly one call to sqlite3_backup_finish() for each
160 successful call to sqlite3_backup_init().</p>
161
162 <p><a name="sqlite3backupinit"></a>
163 <b>sqlite3_backup_init()</b></p>
164
165 <p>The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
166 <a href="../c3ref/sqlite3.html">database connection</a> associated with the destination database
167 and the database name, respectively.
168 The database name is "main" for the main database, "temp" for the
169 temporary database, or the name specified after the AS keyword in
170 an <a href="../lang_attach.html">ATTACH</a> statement for an attached database.
171 The S and M arguments passed to
172 sqlite3_backup_init(D,N,S,M) identify the <a href="../c3ref/sqlite3.html">database connection</a>
173 and database name of the source database, respectively.
174 The source and destination <a href="../c3ref/sqlite3.html">database connections</a> (parameters S and D)
175 must be different or else sqlite3_backup_init(D,N,S,M) will fail with
176 an error.</p>
177
178 <p>A call to sqlite3_backup_init() will fail, returning NULL, if
179 there is already a read or read-write transaction open on the
180 destination database.</p>
181
182 <p>If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
183 returned and an error code and error message are stored in the
184 destination <a href="../c3ref/sqlite3.html">database connection</a> D.
185 The error code and message for the failed call to sqlite3_backup_init()
186 can be retrieved using the <a href="../c3ref/errcode.html">sqlite3_errcode()</a>, <a href="../c3ref/errcode.html">sqlite3_errmsg()</a>, and/or
187 <a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> functions.
188 A successful call to sqlite3_backup_init() returns a pointer to an
189 <a href="../c3ref/backup.html">sqlite3_backup</a> object.
190 The <a href="../c3ref/backup.html">sqlite3_backup</a> object may be used with the sqlite3_backup_step() and
191 sqlite3_backup_finish() functions to perform the specified backup
192 operation.</p>
193
194 <p><a name="sqlite3backupstep"></a>
195 <b>sqlite3_backup_step()</b></p>
196
197 <p>Function sqlite3_backup_step(B,N) will copy up to N pages between
198 the source and destination databases specified by <a href="../c3ref/backup.html">sqlite3_backup</a> object B.
199 If N is negative, all remaining source pages are copied.
200 If sqlite3_backup_step(B,N) successfully copies N pages and there
201 are still more pages to be copied, then the function returns <a href="../rescode.html#ok">SQLITE_OK</a>.
202 If sqlite3_backup_step(B,N) successfully finishes copying all pages
203 from source to destination, then it returns <a href="../rescode.html#done">SQLITE_DONE</a>.
204 If an error occurs while running sqlite3_backup_step(B,N),
205 then an <a href="../rescode.html">error code</a> is returned. As well as <a href="../rescode.html#ok">SQLITE_OK</a> and
206 <a href="../rescode.html#done">SQLITE_DONE</a>, a call to sqlite3_backup_step() may return <a href="../rescode.html#readonly">SQLITE_READONLY</a>,
207 <a href="../rescode.html#nomem">SQLITE_NOMEM</a>, <a href="../rescode.html#busy">SQLITE_BUSY</a>, <a href="../rescode.html#locked">SQLITE_LOCKED</a>, or an
208 <a href="../rescode.html#ioerr_access">SQLITE_IOERR_XXX</a> extended error code.</p>
209
210 <p>The sqlite3_backup_step() might return <a href="../rescode.html#readonly">SQLITE_READONLY</a> if
211 <ol>
212 <li> the destination database was opened read-only, or
213 <li> the destination database is using write-ahead-log journaling
214 and the destination and source page sizes differ, or
215 <li> the destination database is an in-memory database and the
216 destination and source page sizes differ.
217 </ol></p>
218
219 <p>If sqlite3_backup_step() cannot obtain a required file-system lock, then
220 the <a href="../c3ref/busy_handler.html">busy-handler function</a>
221 is invoked (if one is specified). If the
222 busy-handler returns non-zero before the lock is available, then
223 <a href="../rescode.html#busy">SQLITE_BUSY</a> is returned to the caller. In this case the call to
224 sqlite3_backup_step() can be retried later. If the source
225 <a href="../c3ref/sqlite3.html">database connection</a>
226 is being used to write to the source database when sqlite3_backup_step()
227 is called, then <a href="../rescode.html#locked">SQLITE_LOCKED</a> is returned immediately. Again, in this
228 case the call to sqlite3_backup_step() can be retried later on. If
229 <a href="../rescode.html#ioerr_access">SQLITE_IOERR_XXX</a>, <a href="../rescode.html#nomem">SQLITE_NOMEM</a>, or
230 <a href="../rescode.html#readonly">SQLITE_READONLY</a> is returned, then
231 there is no point in retrying the call to sqlite3_backup_step(). These
232 errors are considered fatal. The application must accept
233 that the backup operation has failed and pass the backup operation handle
234 to the sqlite3_backup_finish() to release associated resources.</p>
235
236 <p>The first call to sqlite3_backup_step() obtains an exclusive lock
237 on the destination file. The exclusive lock is not released until either
238 sqlite3_backup_finish() is called or the backup operation is complete
239 and sqlite3_backup_step() returns <a href="../rescode.html#done">SQLITE_DONE</a>. Every call to
240 sqlite3_backup_step() obtains a <a href="../lockingv3.html#shared_lock">shared lock</a> on the source database that
241 lasts for the duration of the sqlite3_backup_step() call.
242 Because the source database is not locked between calls to
243 sqlite3_backup_step(), the source database may be modified mid-way
244 through the backup process. If the source database is modified by an
245 external process or via a database connection other than the one being
246 used by the backup operation, then the backup will be automatically
247 restarted by the next call to sqlite3_backup_step(). If the source
248 database is modified by using the same database connection as is used
249 by the backup operation, then the backup database is automatically
250 updated at the same time.</p>
251
252 <p><a name="sqlite3backupfinish"></a>
253 <b>sqlite3_backup_finish()</b></p>
254
255 <p>When sqlite3_backup_step() has returned <a href="../rescode.html#done">SQLITE_DONE</a>, or when the
256 application wishes to abandon the backup operation, the application
257 should destroy the <a href="../c3ref/backup.html">sqlite3_backup</a> by passing it to sqlite3_backup_finish().
258 The sqlite3_backup_finish() interfaces releases all
259 resources associated with the <a href="../c3ref/backup.html">sqlite3_backup</a> object.
260 If sqlite3_backup_step() has not yet returned <a href="../rescode.html#done">SQLITE_DONE</a>, then any
261 active write-transaction on the destination database is rolled back.
262 The <a href="../c3ref/backup.html">sqlite3_backup</a> object is invalid
263 and may not be used following a call to sqlite3_backup_finish().</p>
264
265 <p>The value returned by sqlite3_backup_finish is <a href="../rescode.html#ok">SQLITE_OK</a> if no
266 sqlite3_backup_step() errors occurred, regardless of whether or not
267 sqlite3_backup_step() completed.
268 If an out-of-memory condition or IO error occurred during any prior
269 sqlite3_backup_step() call on the same <a href="../c3ref/backup.html">sqlite3_backup</a> object, then
270 sqlite3_backup_finish() returns the corresponding <a href="../rescode.html">error code</a>.</p>
271
272 <p>A return of <a href="../rescode.html#busy">SQLITE_BUSY</a> or <a href="../rescode.html#locked">SQLITE_LOCKED</a> from sqlite3_backup_step()
273 is not a permanent error and does not affect the return value of
274 sqlite3_backup_finish().</p>
275
276 <p><a name="sqlite3backupremaining"></a>
277 <a name="sqlite3backuppagecount"></a>
278
279 <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b></p>
280
281 <p>The sqlite3_backup_remaining() routine returns the number of pages still
282 to be backed up at the conclusion of the most recent sqlite3_backup_step().
283 The sqlite3_backup_pagecount() routine returns the total number of pages
284 in the source database at the conclusion of the most recent
285 sqlite3_backup_step().
286 The values returned by these functions are only updated by
287 sqlite3_backup_step(). If the source database is modified in a way that
288 changes the size of the source database or the number of pages remaining,
289 those changes are not reflected in the output of sqlite3_backup_pagecount()
290 and sqlite3_backup_remaining() until after the next
291 sqlite3_backup_step().</p>
292
293 <p><b>Concurrent Usage of Database Handles</b></p>
294
295 <p>The source <a href="../c3ref/sqlite3.html">database connection</a> may be used by the application for other
296 purposes while a backup operation is underway or being initialized.
297 If SQLite is compiled and configured to support threadsafe database
298 connections, then the source database connection may be used concurrently
299 from within other threads.</p>
300
301 <p>However, the application must guarantee that the destination
302 <a href="../c3ref/sqlite3.html">database connection</a> is not passed to any other API (by any thread) after
303 sqlite3_backup_init() is called and before the corresponding call to
304 sqlite3_backup_finish(). SQLite does not currently check to see
305 if the application incorrectly accesses the destination <a href="../c3ref/sqlite3.html">database connection</a>
306 and so no error code is reported, but the operations may malfunction
307 nevertheless. Use of the destination database connection while a
308 backup is in progress might also cause a mutex deadlock.</p>
309
310 <p>If running in <a href="../sharedcache.html">shared cache mode</a>, the application must
311 guarantee that the shared cache used by the destination database
312 is not accessed while the backup is running. In practice this means
313 that the application must guarantee that the disk file being
314 backed up to is not accessed by any connection within the process,
315 not just the specific connection that was passed to sqlite3_backup_init().</p>
316
317 <p>The <a href="../c3ref/backup.html">sqlite3_backup</a> object itself is partially threadsafe. Multiple
318 threads may safely make multiple concurrent calls to sqlite3_backup_step().
319 However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
320 APIs are not strictly speaking threadsafe. If they are invoked at the
321 same time as another thread is invoking sqlite3_backup_step() it is
322 possible that they return invalid values.</p>
323
324 <p><b>Alternatives To Using The Backup API</b></p>
325
326 <p>Other techniques for safely creating a consistent backup of an SQLite
327 database include:</p>
328
329 <p><ul>
330 <li> The <a href="../lang_vacuum.html#vacuuminto">VACUUM INTO</a> command.
331 <li> The <a href="../rsync.html">sqlite3_rsync</a> utility program.
332 </ul>
333 </p><p>See also lists of
334 <a href="../c3ref/objlist.html">Objects</a>,
335 <a href="../c3ref/constlist.html">Constants</a>, and
336 <a href="../c3ref/funclist.html">Functions</a>.</p>
337