/ Check-in [46dd076a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Attempt to improve the documentation for snapshots. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 46dd076af5880e6e9a7de974758b26bc43d0dc074f8143234038fa9cdcc726ee
User & Date: drh 2018-07-23 18:32:42
Context
2018-07-23
18:53
Fix typo of 'SQLITE_OMIT_WINDOWFUNC'. check-in: 8607b84a user: mistachkin tags: trunk
18:32
Attempt to improve the documentation for snapshots. No changes to code. check-in: 46dd076a user: drh tags: trunk
10:57
Fix the macros used to generate the output of "PRAGMA compile_options" so that they handle valid values for the SQLITE_DEFAULT_LOOKASIDE macro (which contain a "," character). check-in: 1cc72845 user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

   883    883   ** is not changed but instead the prior value of that setting is written
   884    884   ** into the array entry, allowing the current retry settings to be
   885    885   ** interrogated.  The zDbName parameter is ignored.
   886    886   **
   887    887   ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
   888    888   ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
   889    889   ** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
   890         -** write ahead log and shared memory files used for transaction control
          890  +** write ahead log ([WAL file]) and shared memory
          891  +** files used for transaction control
   891    892   ** are automatically deleted when the latest connection to the database
   892    893   ** closes.  Setting persistent WAL mode causes those files to persist after
   893    894   ** close.  Persisting the files is useful when other processes that do not
   894    895   ** have write permission on the directory containing the database file want
   895    896   ** to read the database file, as the WAL and shared memory files must exist
   896    897   ** in order for the database to be readable.  The fourth parameter to
   897    898   ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
................................................................................
  8956   8957   ** as ENOSPC, EAUTH, EISDIR, and so forth.  
  8957   8958   */
  8958   8959   int sqlite3_system_errno(sqlite3*);
  8959   8960   
  8960   8961   /*
  8961   8962   ** CAPI3REF: Database Snapshot
  8962   8963   ** KEYWORDS: {snapshot} {sqlite3_snapshot}
  8963         -** EXPERIMENTAL
  8964   8964   **
  8965   8965   ** An instance of the snapshot object records the state of a [WAL mode]
  8966   8966   ** database for some specific point in history.
  8967   8967   **
  8968   8968   ** In [WAL mode], multiple [database connections] that are open on the
  8969   8969   ** same database file can each be reading a different historical version
  8970   8970   ** of the database file.  When a [database connection] begins a read
................................................................................
  8973   8973   ** Subsequent changes to the database from other connections are not seen
  8974   8974   ** by the reader until a new read transaction is started.
  8975   8975   **
  8976   8976   ** The sqlite3_snapshot object records state information about an historical
  8977   8977   ** version of the database file so that it is possible to later open a new read
  8978   8978   ** transaction that sees that historical version of the database rather than
  8979   8979   ** the most recent version.
  8980         -**
  8981         -** The constructor for this object is [sqlite3_snapshot_get()].  The
  8982         -** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
  8983         -** to an historical snapshot (if possible).  The destructor for 
  8984         -** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
  8985   8980   */
  8986   8981   typedef struct sqlite3_snapshot {
  8987   8982     unsigned char hidden[48];
  8988   8983   } sqlite3_snapshot;
  8989   8984   
  8990   8985   /*
  8991   8986   ** CAPI3REF: Record A Database Snapshot
  8992         -** EXPERIMENTAL
         8987  +** CONSTRUCTOR: sqlite3_snapshot
  8993   8988   **
  8994   8989   ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
  8995   8990   ** new [sqlite3_snapshot] object that records the current state of
  8996   8991   ** schema S in database connection D.  ^On success, the
  8997   8992   ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
  8998   8993   ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
  8999   8994   ** If there is not already a read-transaction open on schema S when
................................................................................
  9024   9019   ** whether or not a read transaction is opened on schema S is undefined.
  9025   9020   **
  9026   9021   ** The [sqlite3_snapshot] object returned from a successful call to
  9027   9022   ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
  9028   9023   ** to avoid a memory leak.
  9029   9024   **
  9030   9025   ** The [sqlite3_snapshot_get()] interface is only available when the
  9031         -** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
         9026  +** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9032   9027   */
  9033   9028   SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
  9034   9029     sqlite3 *db,
  9035   9030     const char *zSchema,
  9036   9031     sqlite3_snapshot **ppSnapshot
  9037   9032   );
  9038   9033   
  9039   9034   /*
  9040   9035   ** CAPI3REF: Start a read transaction on an historical snapshot
  9041         -** EXPERIMENTAL
         9036  +** METHOD: sqlite3_snapshot
  9042   9037   **
  9043   9038   ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
  9044   9039   ** read transaction for schema S of
  9045   9040   ** [database connection] D such that the read transaction
  9046   9041   ** refers to historical [snapshot] P, rather than the most
  9047   9042   ** recent change to the database.
  9048   9043   ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
................................................................................
  9062   9057   ** that the database file is in [WAL mode] if there has been no prior
  9063   9058   ** I/O on that database connection, or if the database entered [WAL mode] 
  9064   9059   ** after the most recent I/O on the database connection.)^
  9065   9060   ** (Hint: Run "[PRAGMA application_id]" against a newly opened
  9066   9061   ** database connection in order to make it ready to use snapshots.)
  9067   9062   **
  9068   9063   ** The [sqlite3_snapshot_open()] interface is only available when the
  9069         -** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
         9064  +** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9070   9065   */
  9071   9066   SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
  9072   9067     sqlite3 *db,
  9073   9068     const char *zSchema,
  9074   9069     sqlite3_snapshot *pSnapshot
  9075   9070   );
  9076   9071   
  9077   9072   /*
  9078   9073   ** CAPI3REF: Destroy a snapshot
  9079         -** EXPERIMENTAL
         9074  +** DESTRUCTOR: sqlite3_snapshot
  9080   9075   **
  9081   9076   ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
  9082   9077   ** The application must eventually free every [sqlite3_snapshot] object
  9083   9078   ** using this routine to avoid a memory leak.
  9084   9079   **
  9085   9080   ** The [sqlite3_snapshot_free()] interface is only available when the
  9086         -** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
         9081  +** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
  9087   9082   */
  9088   9083   SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
  9089   9084   
  9090   9085   /*
  9091   9086   ** CAPI3REF: Compare the ages of two snapshot handles.
  9092         -** EXPERIMENTAL
         9087  +** METHOD: sqlite3_snapshot
  9093   9088   **
  9094   9089   ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
  9095   9090   ** of two valid snapshot handles. 
  9096   9091   **
  9097   9092   ** If the two snapshot handles are not associated with the same database 
  9098   9093   ** file, the result of the comparison is undefined. 
  9099   9094   **
................................................................................
  9104   9099   ** clients drops to zero. If either snapshot handle was obtained before the 
  9105   9100   ** wal file was last deleted, the value returned by this function 
  9106   9101   ** is undefined.
  9107   9102   **
  9108   9103   ** Otherwise, this API returns a negative value if P1 refers to an older
  9109   9104   ** snapshot than P2, zero if the two handles refer to the same database
  9110   9105   ** snapshot, and a positive value if P1 is a newer snapshot than P2.
         9106  +**
         9107  +** This interface is only available if SQLite is compiled with the
         9108  +** [SQLITE_ENABLE_SNAPSHOT] option.
  9111   9109   */
  9112   9110   SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
  9113   9111     sqlite3_snapshot *p1,
  9114   9112     sqlite3_snapshot *p2
  9115   9113   );
  9116   9114   
  9117   9115   /*
  9118   9116   ** CAPI3REF: Recover snapshots from a wal file
  9119         -** EXPERIMENTAL
         9117  +** METHOD: sqlite3_snapshot
  9120   9118   **
  9121         -** If all connections disconnect from a database file but do not perform
  9122         -** a checkpoint, the existing wal file is opened along with the database
  9123         -** file the next time the database is opened. At this point it is only
  9124         -** possible to successfully call sqlite3_snapshot_open() to open the most
  9125         -** recent snapshot of the database (the one at the head of the wal file),
  9126         -** even though the wal file may contain other valid snapshots for which
  9127         -** clients have sqlite3_snapshot handles.
         9119  +** If a [WAL file] remains on disk after all database connections close
         9120  +** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control]
         9121  +** or because the last process to have the database opened exited without
         9122  +** calling [sqlite3_close()]) and a new connection is subsequently opened
         9123  +** on that database and [WAL file], the [sqlite3_snapshot_open()] interface
         9124  +** will only be able to open the last transaction added to the WAL file
         9125  +** even though the WAL file contains other valid transactions.
  9128   9126   **
  9129         -** This function attempts to scan the wal file associated with database zDb
         9127  +** This function attempts to scan the WAL file associated with database zDb
  9130   9128   ** of database handle db and make all valid snapshots available to
  9131   9129   ** sqlite3_snapshot_open(). It is an error if there is already a read
  9132         -** transaction open on the database, or if the database is not a wal mode
         9130  +** transaction open on the database, or if the database is not a WAL mode
  9133   9131   ** database.
  9134   9132   **
  9135   9133   ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
         9134  +**
         9135  +** This interface is only available if SQLite is compiled with the
         9136  +** [SQLITE_ENABLE_SNAPSHOT] option.
  9136   9137   */
  9137   9138   SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
  9138   9139   
  9139   9140   /*
  9140   9141   ** CAPI3REF: Serialize a database
  9141   9142   **
  9142   9143   ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory