.Dd January 24, 2024
.Dt SQLITE3_SNAPSHOT_OPEN 3
.Os
.Sh NAME
.Nm sqlite3_snapshot_open
.Nd start a read transaction on an historical snapshot
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_snapshot_open
.Fa "sqlite3 *db"
.Fa "const char *zSchema"
.Fa "sqlite3_snapshot *pSnapshot"
.Fc
.Sh DESCRIPTION
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
.Fn sqlite3_snapshot_open
interface returns SQLITE_OK on success or an appropriate error code
if it fails.
.Pp
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.
.Pp
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.
.Pp
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.
.Pp
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.)
.Pp
The
.Fn sqlite3_snapshot_open
interface is only available when the SQLITE_ENABLE_SNAPSHOT
compile-time option is used.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 10519.
.Bd -literal
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
  sqlite3 *db,
  const char *zSchema,
  sqlite3_snapshot *pSnapshot
);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_get_autocommit 3 ,
.Xr sqlite3_snapshot 3