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