Enhance documentation of sqlite3_snapshot_open() to explain that the database

connection must have participated in at least one read operation prior to
the beginning of the transaction for which the snapshot is to be opened.
Add test cases for this fact.

FossilOrigin-Name: 33dd671cb9c17f08dbc61aed91e80eaeb84bfaf5

diff --git a/manifest b/manifest
index 761f1250c864bf177c726b3b6c5d5c93349c6bad..c218f74566fc2b4f18add333fa997b0322be2010 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\s'Replace.exe'\sto\sthe\sMSVC\sclean\starget.
-D 2016-02-27T00:21:44.269
+C Enhance\sdocumentation\sof\ssqlite3_snapshot_open()\sto\sexplain\sthat\sthe\sdatabase\nconnection\smust\shave\sparticipated\sin\sat\sleast\sone\sread\soperation\sprior\sto\nthe\sbeginning\sof\sthe\stransaction\sfor\swhich\sthe\ssnapshot\sis\sto\sbe\sopened.\nAdd\stest\scases\sfor\sthis\sfact.
+D 2016-02-27T14:00:07.182
 F Makefile.in 4e90dc1521879022aa9479268a4cd141d1771142
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc 4f319afb7c049d40aff7af6e8c4e7cc2ba18e079
@@ -351,7 +351,7 @@ F src/resolve.c b8f7174e5f8c33c44ded3a25a973d0bb89228c20
 F src/rowset.c 9fe4b3ad7cc00944386bb600233d8f523de07a6e
 F src/select.c 1bacfde7b7cec134d2b354cbcf67bafc67078431
 F src/shell.c 89b73e894e737cc2f21e4bce0feb3ea21cc61124
-F src/sqlite.h.in 6bf029bcb077c6db633a77b7fda5ffd5b7c950b7
+F src/sqlite.h.in 57d2a02b14c9ec4f7cb294153eaf62294dc5aa68
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h dfbe62ffd95b99afe2140d8c35b180d11924072d
 F src/sqliteInt.h 63c0e1b5b5d608a1ba2303fe3a554b859a120406
@@ -1034,7 +1034,7 @@ F test/skipscan2.test d1d1450952b7275f0b0a3a981f0230532743951a
 F test/skipscan3.test ec5bab3f81c7038b43450e7b3062e04a198bdbb5
 F test/skipscan5.test 67817a4b6857c47e0e33ba3e506da6f23ef68de2
 F test/skipscan6.test 5866039d03a56f5bd0b3d172a012074a1d90a15b
-F test/snapshot.test 5ec4651d16c3d1eb6c010d102febe32b3614bf56
+F test/snapshot.test c03eb5ba1602df33c1edc1d12393d6ca7a282a46
 F test/snapshot_fault.test 25973aeb1b86a280800e0bcf1eb5ce70e9ef57ab
 F test/soak.test 0b5b6375c9f4110c828070b826b3b4b0bb65cd5f
 F test/softheap1.test 843cd84db9891b2d01b9ab64cef3e9020f98d087
@@ -1451,7 +1451,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 00c8fffd47cec763857389e1e91c026ba3179182
-R 5d5d8a8010dbfa6bc274c104c226fec0
-U mistachkin
-Z b85e54c141d3cf5bd3e41d9206ec3bb6
+P c2277fab12d2aecf9e0f69683741a194df17e854
+R d50b04aa37cc4844a3040bb1385bb8e7
+U drh
+Z f370d53fd3d226317497efdfe8ae225f

diff --git a/manifest.uuid b/manifest.uuid
index 92117cb7f27754e6a4a6eb50407ea3ebf59b7ae5..4954cc1e249cdf0e9d4ad68643cb027ebfb53a05 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-c2277fab12d2aecf9e0f69683741a194df17e854
\ No newline at end of file
+33dd671cb9c17f08dbc61aed91e80eaeb84bfaf5
\ No newline at end of file

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 60e2e3b61cacea331671e0783475b005f5ce72d9..c81a9d0c435c04023eb60e59c9935e9891b689ee 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -7968,7 +7968,11 @@ SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
 ** the first operation, apart from other sqlite3_snapshot_open() calls,
 ** following the [BEGIN] that starts a new read transaction.
 ** ^A [snapshot] will fail to open if it has been overwritten by a 
-** [checkpoint].  
+** [checkpoint].
+** ^A [snapshot] will fail to open if the database connection D has not
+** previously completed at least one read operation against the database 
+** file.  (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.

diff --git a/test/snapshot.test b/test/snapshot.test
index 63a0e30175e81c6a27a011fe76df7e015fedeed5..ba3a6667965eec12e19eb243c9c75b98fa74e6e9 100644 (file)
--- a/test/snapshot.test
+++ b/test/snapshot.test
@@ -334,6 +334,26 @@ do_test 6.3 {
   sqlite3_snapshot_open db2 main $::snapshot
   db2 eval { SELECT * FROM x1 }
 } {z zz zzz}
+do_test 6.4 {
+  db2 close
+  sqlite3 db2 test.db 
+  db2 eval "PRAGMA application_id"
+  db2 eval "BEGIN"
+  sqlite3_snapshot_open db2 main $::snapshot
+  db2 eval { SELECT * FROM x1 }
+} {z zz zzz}
+
+# EVIDENCE-OF: R-55491-50411 A snapshot will fail to open if the
+# database connection D has not previously completed at least one read
+# operation against the database file.
+#
+do_test 6.5 {
+  db2 close
+  sqlite3 db2 test.db 
+  db2 eval "BEGIN"
+  list [catch {sqlite3_snapshot_open db2 main $::snapshot} msg] $msg
+} {1 SQLITE_ERROR}
+
 sqlite3_snapshot_free $snapshot
 
 finish_test