1.Dd December 19, 2018 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 78A call to sqlite3_backup_init() will fail, returning NULL, if there 79is already a read or read-write transaction open on the destination 80database. 81.Pp 82If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is 83returned and an error code and error message are stored in the destination 84database connection D. 85The error code and message for the failed call to sqlite3_backup_init() 86can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), 87and/or sqlite3_errmsg16() functions. 88A successful call to sqlite3_backup_init() returns a pointer to an 89sqlite3_backup object. 90The sqlite3_backup object may be used with the sqlite3_backup_step() 91and sqlite3_backup_finish() functions to perform the specified backup 92operation. 93.Pp 94\fBsqlite3_backup_step()\fP 95.Pp 96Function sqlite3_backup_step(B,N) will copy up to N pages between the 97source and destination databases specified by sqlite3_backup 98object B. 99If N is negative, all remaining source pages are copied. 100If sqlite3_backup_step(B,N) successfully copies N pages and there are 101still more pages to be copied, then the function returns SQLITE_OK. 102If sqlite3_backup_step(B,N) successfully finishes copying all pages 103from source to destination, then it returns SQLITE_DONE. 104If an error occurs while running sqlite3_backup_step(B,N), then an 105error code is returned. 106As well as SQLITE_OK and SQLITE_DONE, a call to 107sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, 108SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX 109extended error code. 110.Pp 111The sqlite3_backup_step() might return SQLITE_READONLY 112if 113.Bl -enum 114.It 115the destination database was opened read-only, or 116.It 117the destination database is using write-ahead-log journaling and the 118destination and source page sizes differ, or 119.It 120the destination database is an in-memory database and the destination 121and source page sizes differ. 122.El 123.Pp 124If sqlite3_backup_step() cannot obtain a required file-system lock, 125then the busy-handler function is invoked (if 126one is specified). 127If the busy-handler returns non-zero before the lock is available, 128then SQLITE_BUSY is returned to the caller. 129In this case the call to sqlite3_backup_step() can be retried later. 130If the source database connection is being used 131to write to the source database when sqlite3_backup_step() is called, 132then SQLITE_LOCKED is returned immediately. 133Again, in this case the call to sqlite3_backup_step() can be retried 134later on. 135If SQLITE_IOERR_XXX, SQLITE_NOMEM, or 136SQLITE_READONLY is returned, then there is no point 137in retrying the call to sqlite3_backup_step(). 138These errors are considered fatal. 139The application must accept that the backup operation has failed and 140pass the backup operation handle to the sqlite3_backup_finish() to 141release associated resources. 142.Pp 143The first call to sqlite3_backup_step() obtains an exclusive lock on 144the destination file. 145The exclusive lock is not released until either sqlite3_backup_finish() 146is called or the backup operation is complete and sqlite3_backup_step() 147returns SQLITE_DONE. 148Every call to sqlite3_backup_step() obtains a shared lock 149on the source database that lasts for the duration of the sqlite3_backup_step() 150call. 151Because the source database is not locked between calls to sqlite3_backup_step(), 152the source database may be modified mid-way through the backup process. 153If the source database is modified by an external process or via a 154database connection other than the one being used by the backup operation, 155then the backup will be automatically restarted by the next call to 156sqlite3_backup_step(). 157If the source database is modified by the using the same database connection 158as is used by the backup operation, then the backup database is automatically 159updated at the same time. 160.Pp 161\fBsqlite3_backup_finish()\fP 162.Pp 163When sqlite3_backup_step() has returned SQLITE_DONE, or 164when the application wishes to abandon the backup operation, the application 165should destroy the sqlite3_backup by passing it to sqlite3_backup_finish(). 166The sqlite3_backup_finish() interfaces releases all resources associated 167with the sqlite3_backup object. 168If sqlite3_backup_step() has not yet returned SQLITE_DONE, 169then any active write-transaction on the destination database is rolled 170back. 171The sqlite3_backup object is invalid and may not be used 172following a call to sqlite3_backup_finish(). 173.Pp 174The value returned by sqlite3_backup_finish is SQLITE_OK if 175no sqlite3_backup_step() errors occurred, regardless or whether or 176not sqlite3_backup_step() completed. 177If an out-of-memory condition or IO error occurred during any prior 178sqlite3_backup_step() call on the same sqlite3_backup 179object, then sqlite3_backup_finish() returns the corresponding error code. 180.Pp 181A return of SQLITE_BUSY or SQLITE_LOCKED from 182sqlite3_backup_step() is not a permanent error and does not affect 183the return value of sqlite3_backup_finish(). 184.Pp 185\fBsqlite3_backup_remaining() and sqlite3_backup_pagecount()\fP 186.Pp 187The sqlite3_backup_remaining() routine returns the number of pages 188still to be backed up at the conclusion of the most recent sqlite3_backup_step(). 189The sqlite3_backup_pagecount() routine returns the total number of 190pages in the source database at the conclusion of the most recent sqlite3_backup_step(). 191The values returned by these functions are only updated by sqlite3_backup_step(). 192If the source database is modified in a way that changes the size of 193the source database or the number of pages remaining, those changes 194are not reflected in the output of sqlite3_backup_pagecount() and sqlite3_backup_remaining() 195until after the next sqlite3_backup_step(). 196.Pp 197\fBConcurrent Usage of Database Handles\fP 198.Pp 199The source database connection may be used by the 200application for other purposes while a backup operation is underway 201or being initialized. 202If SQLite is compiled and configured to support threadsafe database 203connections, then the source database connection may be used concurrently 204from within other threads. 205.Pp 206However, the application must guarantee that the destination database connection 207is not passed to any other API (by any thread) after sqlite3_backup_init() 208is called and before the corresponding call to sqlite3_backup_finish(). 209SQLite does not currently check to see if the application incorrectly 210accesses the destination database connection and 211so no error code is reported, but the operations may malfunction nevertheless. 212Use of the destination database connection while a backup is in progress 213might also also cause a mutex deadlock. 214.Pp 215If running in shared cache mode, the application must 216guarantee that the shared cache used by the destination database is 217not accessed while the backup is running. 218In practice this means that the application must guarantee that the 219disk file being backed up to is not accessed by any connection within 220the process, not just the specific connection that was passed to sqlite3_backup_init(). 221.Pp 222The sqlite3_backup object itself is partially threadsafe. 223Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). 224However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() 225APIs are not strictly speaking threadsafe. 226If they are invoked at the same time as another thread is invoking 227sqlite3_backup_step() it is possible that they return invalid values. 228.Sh SEE ALSO 229.Xr sqlite3 3 , 230.Xr sqlite3_backup 3 , 231.Xr sqlite3_busy_handler 3 , 232.Xr sqlite3_errcode 3 , 233.Xr SQLITE_OK 3 , 234.Xr SQLITE_ERROR_MISSING_COLLSEQ 3 , 235.Xr SQLITE_OK 3 236