sqlite3_snapshot_open

Navigation

API > API/Plugins > API/Plugins/SQLiteCore > API/Plugins/SQLiteCore/sqlite

References

int sqlite3_snapshot_open  
(  
    sqlite3 * db,  
    const char * zSchema,  
    sqlite3_snapshot * pSnapshot  
)  
Copy full snippet

int sqlite3_snapshot_open (     sqlite3 * db,     const char * zSchema,     sqlite3_snapshot * pSnapshot )

Remarks

CAPI3REF: Start a read transaction on an historical snapshot METHOD: sqlite3_snapshot

^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read transaction or upgrades an existing one for schema S of [database connection] D such that the read transaction refers to historical [snapshot] P, rather than the most recent change to the database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success or an appropriate [error code] if it fails.

^In order to succeed, the database connection must not be in [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there is already a read transaction open on schema S, then the database handle must have no active statements (SELECT statements that have been passed to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()). SQLITE_ERROR is returned if either of these conditions is violated, or if schema S does not exist, or if the snapshot object is invalid.

^A call to sqlite3_snapshot_open() will fail to open if the specified snapshot has been overwritten by a [checkpoint]. In this case SQLITE_ERROR_SNAPSHOT is returned.

If there is already a read transaction open when this function is invoked, then the same read transaction remains open (on the same database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT is returned. If another error code - for example SQLITE_PROTOCOL or an SQLITE_IOERR error code - is returned, then the final state of the read transaction is undefined. If SQLITE_OK is returned, then the read transaction is now open on database snapshot P.

^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the database connection D does not know that the database file for schema S is in [WAL mode]. A database connection might not know that the database file is in [WAL mode] if there has been no prior I/O on that database connection, or if the database entered [WAL mode] after the most recent I/O on the database connection.)^ (Hint: Run "[PRAGMA application_id]" against a newly opened database connection in order to make it ready to use snapshots.)

The [sqlite3_snapshot_open()] interface is only available when the [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.