1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Online Backup API.</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Online Backup API.</h2><blockquote><pre>sqlite3_backup *sqlite3_backup_init(
121
sqlite3 *pDest, /* Destination database handle */
122
const char *zDestName, /* Destination database name */
123
sqlite3 *pSource, /* Source database handle */
124
const char *zSourceName /* Source database name */
126
int sqlite3_backup_step(sqlite3_backup *p, int nPage);
127
int sqlite3_backup_finish(sqlite3_backup *p);
128
int sqlite3_backup_remaining(sqlite3_backup *p);
129
int sqlite3_backup_pagecount(sqlite3_backup *p);
130
</pre></blockquote><p>
131
The backup API copies the content of one database into another.
132
It is useful either for creating backups of databases or
133
for copying in-memory databases to or from persistent files.</p>
135
<p>See Also: <a href="../backup.html">Using the SQLite Online Backup API</a></p>
137
<p>SQLite holds a write transaction open on the destination database file
138
for the duration of the backup operation.
139
The source database is read-locked only while it is being read;
140
it is not locked continuously for the entire backup operation.
141
Thus, the backup may be performed on a live source database without
142
preventing other database connections from
143
reading or writing to the source database while the backup is underway.</p>
145
<p>To perform a backup operation:
147
<li><b>sqlite3_backup_init()</b> is called once to initialize the
149
<li><b>sqlite3_backup_step()</b> is called one or more times to transfer
150
the data between the two databases, and finally
151
<li><b>sqlite3_backup_finish()</b> is called to release all resources
152
associated with the backup operation.
154
There should be exactly one call to sqlite3_backup_finish() for each
155
successful call to sqlite3_backup_init().</p>
157
<p><a name="sqlite3backupinit"></a>
158
<b>sqlite3_backup_init()</b></p>
160
<p>The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
161
<a href="../c3ref/sqlite3.html">database connection</a> associated with the destination database
162
and the database name, respectively.
163
The database name is "main" for the main database, "temp" for the
164
temporary database, or the name specified after the AS keyword in
165
an <a href="../lang_attach.html">ATTACH</a> statement for an attached database.
166
The S and M arguments passed to
167
sqlite3_backup_init(D,N,S,M) identify the <a href="../c3ref/sqlite3.html">database connection</a>
168
and database name of the source database, respectively.
169
The source and destination <a href="../c3ref/sqlite3.html">database connections</a> (parameters S and D)
170
must be different or else sqlite3_backup_init(D,N,S,M) will fail with
173
<p>If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
174
returned and an error code and error message are stored in the
175
destination <a href="../c3ref/sqlite3.html">database connection</a> D.
176
The error code and message for the failed call to sqlite3_backup_init()
177
can be retrieved using the <a href="../c3ref/errcode.html">sqlite3_errcode()</a>, <a href="../c3ref/errcode.html">sqlite3_errmsg()</a>, and/or
178
<a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> functions.
179
A successful call to sqlite3_backup_init() returns a pointer to an
180
<a href="../c3ref/backup.html">sqlite3_backup</a> object.
181
The <a href="../c3ref/backup.html">sqlite3_backup</a> object may be used with the sqlite3_backup_step() and
182
sqlite3_backup_finish() functions to perform the specified backup
185
<p><a name="sqlite3backupstep"></a>
186
<b>sqlite3_backup_step()</b></p>
188
<p>Function sqlite3_backup_step(B,N) will copy up to N pages between
189
the source and destination databases specified by <a href="../c3ref/backup.html">sqlite3_backup</a> object B.
190
If N is negative, all remaining source pages are copied.
191
If sqlite3_backup_step(B,N) successfully copies N pages and there
192
are still more pages to be copied, then the function returns <a href="../c3ref/c_abort.html">SQLITE_OK</a>.
193
If sqlite3_backup_step(B,N) successfully finishes copying all pages
194
from source to destination, then it returns <a href="../c3ref/c_abort.html">SQLITE_DONE</a>.
195
If an error occurs while running sqlite3_backup_step(B,N),
196
then an <a href="../c3ref/c_abort.html">error code</a> is returned. As well as <a href="../c3ref/c_abort.html">SQLITE_OK</a> and
197
<a href="../c3ref/c_abort.html">SQLITE_DONE</a>, a call to sqlite3_backup_step() may return <a href="../c3ref/c_abort.html">SQLITE_READONLY</a>,
198
<a href="../c3ref/c_abort.html">SQLITE_NOMEM</a>, <a href="../c3ref/c_abort.html">SQLITE_BUSY</a>, <a href="../c3ref/c_abort.html">SQLITE_LOCKED</a>, or an
199
<a href="../c3ref/c_abort_rollback.html">SQLITE_IOERR_XXX</a> extended error code.</p>
201
<p>The sqlite3_backup_step() might return <a href="../c3ref/c_abort.html">SQLITE_READONLY</a> if
203
<li> the destination database was opened read-only, or
204
<li> the destination database is using write-ahead-log journaling
205
and the destination and source page sizes differ, or
206
<li> the destination database is an in-memory database and the
207
destination and source page sizes differ.
210
<p>If sqlite3_backup_step() cannot obtain a required file-system lock, then
211
the <a href="../c3ref/busy_handler.html">busy-handler function</a>
212
is invoked (if one is specified). If the
213
busy-handler returns non-zero before the lock is available, then
214
<a href="../c3ref/c_abort.html">SQLITE_BUSY</a> is returned to the caller. In this case the call to
215
sqlite3_backup_step() can be retried later. If the source
216
<a href="../c3ref/sqlite3.html">database connection</a>
217
is being used to write to the source database when sqlite3_backup_step()
218
is called, then <a href="../c3ref/c_abort.html">SQLITE_LOCKED</a> is returned immediately. Again, in this
219
case the call to sqlite3_backup_step() can be retried later on. If
220
<a href="../c3ref/c_abort_rollback.html">SQLITE_IOERR_XXX</a>, <a href="../c3ref/c_abort.html">SQLITE_NOMEM</a>, or
221
<a href="../c3ref/c_abort.html">SQLITE_READONLY</a> is returned, then
222
there is no point in retrying the call to sqlite3_backup_step(). These
223
errors are considered fatal. The application must accept
224
that the backup operation has failed and pass the backup operation handle
225
to the sqlite3_backup_finish() to release associated resources.</p>
227
<p>The first call to sqlite3_backup_step() obtains an exclusive lock
228
on the destination file. The exclusive lock is not released until either
229
sqlite3_backup_finish() is called or the backup operation is complete
230
and sqlite3_backup_step() returns <a href="../c3ref/c_abort.html">SQLITE_DONE</a>. Every call to
231
sqlite3_backup_step() obtains a <a href="../lockingv3.html#shared_lock">shared lock</a> on the source database that
232
lasts for the duration of the sqlite3_backup_step() call.
233
Because the source database is not locked between calls to
234
sqlite3_backup_step(), the source database may be modified mid-way
235
through the backup process. If the source database is modified by an
236
external process or via a database connection other than the one being
237
used by the backup operation, then the backup will be automatically
238
restarted by the next call to sqlite3_backup_step(). If the source
239
database is modified by the using the same database connection as is used
240
by the backup operation, then the backup database is automatically
241
updated at the same time.</p>
243
<p><a name="sqlite3backupfinish"></a>
244
<b>sqlite3_backup_finish()</b></p>
246
<p>When sqlite3_backup_step() has returned <a href="../c3ref/c_abort.html">SQLITE_DONE</a>, or when the
247
application wishes to abandon the backup operation, the application
248
should destroy the <a href="../c3ref/backup.html">sqlite3_backup</a> by passing it to sqlite3_backup_finish().
249
The sqlite3_backup_finish() interfaces releases all
250
resources associated with the <a href="../c3ref/backup.html">sqlite3_backup</a> object.
251
If sqlite3_backup_step() has not yet returned <a href="../c3ref/c_abort.html">SQLITE_DONE</a>, then any
252
active write-transaction on the destination database is rolled back.
253
The <a href="../c3ref/backup.html">sqlite3_backup</a> object is invalid
254
and may not be used following a call to sqlite3_backup_finish().</p>
256
<p>The value returned by sqlite3_backup_finish is <a href="../c3ref/c_abort.html">SQLITE_OK</a> if no
257
sqlite3_backup_step() errors occurred, regardless or whether or not
258
sqlite3_backup_step() completed.
259
If an out-of-memory condition or IO error occurred during any prior
260
sqlite3_backup_step() call on the same <a href="../c3ref/backup.html">sqlite3_backup</a> object, then
261
sqlite3_backup_finish() returns the corresponding <a href="../c3ref/c_abort.html">error code</a>.</p>
263
<p>A return of <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> or <a href="../c3ref/c_abort.html">SQLITE_LOCKED</a> from sqlite3_backup_step()
264
is not a permanent error and does not affect the return value of
265
sqlite3_backup_finish().</p>
267
<p><a name="sqlite3backupremaining"></a>
268
<a name="sqlite3backuppagecount"></a>
270
<b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b></p>
272
<p>Each call to sqlite3_backup_step() sets two values inside
273
the <a href="../c3ref/backup.html">sqlite3_backup</a> object: the number of pages still to be backed
274
up and the total number of pages in the source database file.
275
The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
276
retrieve these two values, respectively.</p>
278
<p>The values returned by these functions are only updated by
279
sqlite3_backup_step(). If the source database is modified during a backup
280
operation, then the values are not updated to account for any extra
281
pages that need to be updated or the size of the source database file
284
<p><b>Concurrent Usage of Database Handles</b></p>
286
<p>The source <a href="../c3ref/sqlite3.html">database connection</a> may be used by the application for other
287
purposes while a backup operation is underway or being initialized.
288
If SQLite is compiled and configured to support threadsafe database
289
connections, then the source database connection may be used concurrently
290
from within other threads.</p>
292
<p>However, the application must guarantee that the destination
293
<a href="../c3ref/sqlite3.html">database connection</a> is not passed to any other API (by any thread) after
294
sqlite3_backup_init() is called and before the corresponding call to
295
sqlite3_backup_finish(). SQLite does not currently check to see
296
if the application incorrectly accesses the destination <a href="../c3ref/sqlite3.html">database connection</a>
297
and so no error code is reported, but the operations may malfunction
298
nevertheless. Use of the destination database connection while a
299
backup is in progress might also also cause a mutex deadlock.</p>
301
<p>If running in <a href="../sharedcache.html">shared cache mode</a>, the application must
302
guarantee that the shared cache used by the destination database
303
is not accessed while the backup is running. In practice this means
304
that the application must guarantee that the disk file being
305
backed up to is not accessed by any connection within the process,
306
not just the specific connection that was passed to sqlite3_backup_init().</p>
308
<p>The <a href="../c3ref/backup.html">sqlite3_backup</a> object itself is partially threadsafe. Multiple
309
threads may safely make multiple concurrent calls to sqlite3_backup_step().
310
However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
311
APIs are not strictly speaking threadsafe. If they are invoked at the
312
same time as another thread is invoking sqlite3_backup_step() it is
313
possible that they return invalid values.
314
</p><p>See also lists of
315
<a href="objlist.html">Objects</a>,
316
<a href="constlist.html">Constants</a>, and
317
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/backup_finish.html
