1.Dd December 19, 2018 2.Dt SQLITE3_SNAPSHOT_OPEN 3 3.Os 4.Sh NAME 5.Nm sqlite3_snapshot_open 6.Nd Start a read transaction on an historical snapshot 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_snapshot_open 10.Fa "sqlite3 *db" 11.Fa "const char *zSchema" 12.Fa "sqlite3_snapshot *pSnapshot " 13.Fc 14.Sh DESCRIPTION 15The sqlite3_snapshot_open(D,S,P) interface 16either starts a new read transaction or upgrades an existing one for 17schema S of database connection D such that the 18read transaction refers to historical snapshot P, rather than 19the most recent change to the database. 20The sqlite3_snapshot_open() interface returns 21SQLITE_OK on success or an appropriate error code if it fails. 22.Pp 23In order to succeed, the database connection must not be in autocommit mode 24when sqlite3_snapshot_open(D,S,P) is called. 25If there is already a read transaction open on schema S, then the database 26handle must have no active statements (SELECT statements that have 27been passed to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()). 28SQLITE_ERROR is returned if either of these conditions is violated, 29or if schema S does not exist, or if the snapshot object is invalid. 30.Pp 31A call to sqlite3_snapshot_open() will fail to open if the specified 32snapshot has been overwritten by a checkpoint. 33In this case SQLITE_ERROR_SNAPSHOT is returned. 34.Pp 35If there is already a read transaction open when this function is invoked, 36then the same read transaction remains open (on the same database snapshot) 37if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT is returned. 38If another error code - for example SQLITE_PROTOCOL or an SQLITE_IOERR 39error code - is returned, then the final state of the read transaction 40is undefined. 41If SQLITE_OK is returned, then the read transaction is now open on 42database snapshot P. 43.Pp 44A call to sqlite3_snapshot_open(D,S,P) 45will fail if the database connection D does not know that the database 46file for schema S is in WAL mode. 47A database connection might not know that the database file is in WAL mode 48if there has been no prior I/O on that database connection, or if the 49database entered WAL mode after the most recent I/O on the 50database connection. 51(Hint: Run "PRAGMA application_id" against a newly 52opened database connection in order to make it ready to use snapshots.) 53.Pp 54The sqlite3_snapshot_open() interface is only 55available when the SQLITE_ENABLE_SNAPSHOT compile-time 56option is used. 57.Sh SEE ALSO 58.Xr sqlite3_get_autocommit 3 , 59.Xr sqlite3 3 , 60.Xr sqlite3_snapshot 3 , 61.Xr sqlite3_snapshot_open 3 62