1.Dd $Mdocdate$ 2.Dt SQLITE3_BACKUP_INIT 3 3.Os 4.Sh NAME 5.Nm sqlite3_backup_init , 6.Nm sqlite3_backup_step , 7.Nm sqlite3_backup_finish , 8.Nm sqlite3_backup_remaining , 9.Nm sqlite3_backup_pagecount 10.Nd Online Backup API. 11.Sh SYNOPSIS 12.Ft sqlite3_backup * 13.Fo sqlite3_backup_init 14.Fa "sqlite3 *pDest" 15.Fa "const char *zDestName" 16.Fa "sqlite3 *pSource" 17.Fa "const char *zSourceName " 18.Fc 19.Ft int 20.Fo sqlite3_backup_step 21.Fa "sqlite3_backup *p" 22.Fa "int nPage" 23.Fc 24.Ft int 25.Fo sqlite3_backup_finish 26.Fa "sqlite3_backup *p" 27.Fc 28.Ft int 29.Fo sqlite3_backup_remaining 30.Fa "sqlite3_backup *p" 31.Fc 32.Ft int 33.Fo sqlite3_backup_pagecount 34.Fa "sqlite3_backup *p" 35.Fc 36.Sh DESCRIPTION 37The backup API copies the content of one database into another. 38It is useful either for creating backups of databases or for copying 39in-memory databases to or from persistent files. 40.Pp 41SQLite holds a write transaction open on the destination database file 42for the duration of the backup operation. 43The source database is read-locked only while it is being read; it 44is not locked continuously for the entire backup operation. 45Thus, the backup may be performed on a live source database without 46preventing other database connections from reading or writing to the 47source database while the backup is underway. 48.Pp 49To perform a backup operation: 50.Bl -enum 51.It 52\fBsqlite3_backup_init()\fP is called once to initialize the backup, 53.It 54\fBsqlite3_backup_step()\fP is called one or more times to transfer the data 55between the two databases, and finally 56.It 57\fBsqlite3_backup_finish()\fP is called to release all resources associated 58with the backup operation. 59.El 60.Pp 61There should be exactly one call to sqlite3_backup_finish() for each 62successful call to sqlite3_backup_init(). 63.Pp 64\fBsqlite3_backup_init()\fP 65.Pp 66The D and N arguments to sqlite3_backup_init(D,N,S,M) are the database connection 67associated with the destination database and the database name, respectively. 68The database name is "main" for the main database, "temp" for the temporary 69database, or the name specified after the AS keyword in an ATTACH 70statement for an attached database. 71The S and M arguments passed to sqlite3_backup_init(D,N,S,M) identify 72the database connection and database name of the 73source database, respectively. 74The source and destination database connections 75(parameters S and D) must be different or else sqlite3_backup_init(D,N,S,M) 76will fail with an error. 77.Pp 78If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is 79returned and an error code and error message are stored in the destination 80database connection D. 81The error code and message for the failed call to sqlite3_backup_init() 82can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), 83and/or sqlite3_errmsg16() functions. 84A successful call to sqlite3_backup_init() returns a pointer to an 85sqlite3_backup object. 86The sqlite3_backup object may be used with the sqlite3_backup_step() 87and sqlite3_backup_finish() functions to perform the specified backup 88operation. 89.Pp 90\fBsqlite3_backup_step()\fP 91.Pp 92Function sqlite3_backup_step(B,N) will copy up to N pages between the 93source and destination databases specified by sqlite3_backup 94object B. 95If N is negative, all remaining source pages are copied. 96If sqlite3_backup_step(B,N) successfully copies N pages and there are 97still more pages to be copied, then the function returns SQLITE_OK. 98If sqlite3_backup_step(B,N) successfully finishes copying all pages 99from source to destination, then it returns SQLITE_DONE. 100If an error occurs while running sqlite3_backup_step(B,N), then an 101error code is returned. 102As well as SQLITE_OK and SQLITE_DONE, a call to 103sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, 104SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX 105extended error code. 106.Pp 107The sqlite3_backup_step() might return SQLITE_READONLY 108if 109.Bl -enum 110.It 111the destination database was opened read-only, or 112.It 113the destination database is using write-ahead-log journaling and the 114destination and source page sizes differ, or 115.It 116the destination database is an in-memory database and the destination 117and source page sizes differ. 118.El 119.Pp 120If sqlite3_backup_step() cannot obtain a required file-system lock, 121then the busy-handler function is invoked (if 122one is specified). 123If the busy-handler returns non-zero before the lock is available, 124then SQLITE_BUSY is returned to the caller. 125In this case the call to sqlite3_backup_step() can be retried later. 126If the source database connection is being used 127to write to the source database when sqlite3_backup_step() is called, 128then SQLITE_LOCKED is returned immediately. 129Again, in this case the call to sqlite3_backup_step() can be retried 130later on. 131If SQLITE_IOERR_XXX, SQLITE_NOMEM, or 132SQLITE_READONLY is returned, then there is no point 133in retrying the call to sqlite3_backup_step(). 134These errors are considered fatal. 135The application must accept that the backup operation has failed and 136pass the backup operation handle to the sqlite3_backup_finish() to 137release associated resources. 138.Pp 139The first call to sqlite3_backup_step() obtains an exclusive lock on 140the destination file. 141The exclusive lock is not released until either sqlite3_backup_finish() 142is called or the backup operation is complete and sqlite3_backup_step() 143returns SQLITE_DONE. 144Every call to sqlite3_backup_step() obtains a shared lock 145on the source database that lasts for the duration of the sqlite3_backup_step() 146call. 147Because the source database is not locked between calls to sqlite3_backup_step(), 148the source database may be modified mid-way through the backup process. 149If the source database is modified by an external process or via a 150database connection other than the one being used by the backup operation, 151then the backup will be automatically restarted by the next call to 152sqlite3_backup_step(). 153If the source database is modified by the using the same database connection 154as is used by the backup operation, then the backup database is automatically 155updated at the same time. 156.Pp 157\fBsqlite3_backup_finish()\fP 158.Pp 159When sqlite3_backup_step() has returned SQLITE_DONE, or 160when the application wishes to abandon the backup operation, the application 161should destroy the sqlite3_backup by passing it to sqlite3_backup_finish(). 162The sqlite3_backup_finish() interfaces releases all resources associated 163with the sqlite3_backup object. 164If sqlite3_backup_step() has not yet returned SQLITE_DONE, 165then any active write-transaction on the destination database is rolled 166back. 167The sqlite3_backup object is invalid and may not be used 168following a call to sqlite3_backup_finish(). 169.Pp 170The value returned by sqlite3_backup_finish is SQLITE_OK if 171no sqlite3_backup_step() errors occurred, regardless or whether or 172not sqlite3_backup_step() completed. 173If an out-of-memory condition or IO error occurred during any prior 174sqlite3_backup_step() call on the same sqlite3_backup 175object, then sqlite3_backup_finish() returns the corresponding error code. 176.Pp 177A return of SQLITE_BUSY or SQLITE_LOCKED from 178sqlite3_backup_step() is not a permanent error and does not affect 179the return value of sqlite3_backup_finish(). 180.Pp 181\fBsqlite3_backup_remaining() and sqlite3_backup_pagecount()\fP 182.Pp 183Each call to sqlite3_backup_step() sets two values inside the sqlite3_backup 184object: the number of pages still to be backed up and the total number 185of pages in the source database file. 186The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces 187retrieve these two values, respectively. 188.Pp 189The values returned by these functions are only updated by sqlite3_backup_step(). 190If the source database is modified during a backup operation, then 191the values are not updated to account for any extra pages that need 192to be updated or the size of the source database file changing. 193.Pp 194\fBConcurrent Usage of Database Handles\fP 195.Pp 196The source database connection may be used by the 197application for other purposes while a backup operation is underway 198or being initialized. 199If SQLite is compiled and configured to support threadsafe database 200connections, then the source database connection may be used concurrently 201from within other threads. 202.Pp 203However, the application must guarantee that the destination database connection 204is not passed to any other API (by any thread) after sqlite3_backup_init() 205is called and before the corresponding call to sqlite3_backup_finish(). 206SQLite does not currently check to see if the application incorrectly 207accesses the destination database connection and 208so no error code is reported, but the operations may malfunction nevertheless. 209Use of the destination database connection while a backup is in progress 210might also also cause a mutex deadlock. 211.Pp 212If running in shared cache mode, the application must 213guarantee that the shared cache used by the destination database is 214not accessed while the backup is running. 215In practice this means that the application must guarantee that the 216disk file being backed up to is not accessed by any connection within 217the process, not just the specific connection that was passed to sqlite3_backup_init(). 218.Pp 219The sqlite3_backup object itself is partially threadsafe. 220Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). 221However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() 222APIs are not strictly speaking threadsafe. 223If they are invoked at the same time as another thread is invoking 224sqlite3_backup_step() it is possible that they return invalid values. 225.Sh SEE ALSO 226.Xr sqlite3 3 , 227.Xr SQLITE_OK 3 , 228.Xr sqlite3_backup 3 , 229.Xr sqlite3_busy_handler 3 , 230.Xr sqlite3_errcode 3 , 231.Xr SQLITE_OK 3 , 232.Xr SQLITE_IOERR_READ 3 , 233.Xr SQLITE_OK 3 234