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