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