[TEST] sqlite3-3.7.17-3

[Warren Young]

This is the first formal test release of SQLite 3.7.17.  These are -3 
packages because there were two informal test releases prior to this.

Because it is a "test" release, you have to select it specially from the 
setup.exe packages screen.  You still get 3.7.16.2-1 by default.

Aside from tracking the upstream .17 release, this Cygwin build does 
many things, which is why I am going through a multistage test sequence. 
  This is the last stage before final release.



Heretofore, Cygwin SQLite has been built in "Cygwin mode," where SQLite 
bypasses the Cygwin DLL for some calls, particularly in regards to file 
locking.  These calls go straight to the Win32 API.  This lets Cygwin 
SQLite do file locking the same way native Win32 builds of SQLite do, so 
that any pair of programs can cooperate in their use of a single DB 
file, regardless of which version of SQLite they are built against.

I did once (3.7.12.1-1) ship Cygwin SQLite built the other way, in "Unix 
mode," which forces the SQLite code to treat Cygwin as any other POSIX 
platform.  This has the benefit that file locking works the way POSIX 
programs expect, but it breaks compatibility with the huge number of 
programs built against native SQLite.

This gave me a choice of evils: I could choose to break compatibility 
with native Win32 programs, or I could break compatibility with other 
Cygwin programs.  I chose the second option, simply because there are 
more native Win32 programs than Cygwin programs using SQLite.

This impasse was broken -- we hope -- by a feature added by Corinna in 
Cygwin 1.7.19 and extended in 1.7.20.  It allows a program -- such as 
Cygwin SQLite -- to request that the DLL do file locking in a way more 
compatible with native Windows programs.  This release uses this new 
feature by default, so that despite being built in Unix mode, it should 
still interoperate with native Windows programs that also use SQLite.

You do require Cygwin 1.7.20 to properly test this new package.  The 
variant of the feature in 1.7.19 doesn't work for SQLite, so this -3 
test release no longer has code to attempt to enable it.  (The original 
version of this new feature may still be useful to other programs, so it 
hasn't been removed from the Cygwin DLL.)  These new packages will still 
run under Cygwin 1.7.18 and earlier, but they will behave the same as 
the ill-fated SQLite 3.7.12.1 release in regards to locking.

If you have had problems in the past with SQLite interoperability with 
native Windows programs, please test with this new release.  You 
shouldn't have to do anything to test its interoperability with native 
Windows programs.

If your interop problems were with other Cygwin programs, then you want 
to set the new CYGWIN_SQLITE_LOCKING environment variable to "posix". 
(Case doesn't matter.)  This will suppress Cygwin SQLite's call to the 
new Cygwin API, so it behaves like a stock Unix mode build.

Because this test release removes the "posixmand" feature, if you tested 
the -1 or -2 releases, I ask that you re-test with -3.  I believe you 
will see no change, but y'all are the ones with all the important test 
cases. :)



This version of Cygwin SQLite also makes one other big, potentially 
breaking change: temporary files are created in-memory exclusively, by 
default.

There is some concern that this could cause problems with huge DB files 
on 32-bit Cygwin.  If this version of SQLite fails with some 
out-of-memory error with your DB, there is a pragma you can set to make 
it behave the old way:

	https://www.sqlite.org/pragma.html#pragma_temp_store

If setting this pragma to 1 fixes such an error, I want to hear it! 
(I'd also be curious to know how big the DB file is, and how much RAM 
there is in your machine.)

Note that this isn't the same thing as loading the entire DB into RAM. 
If your DB is, say, 5 GB, you needn't worry about 4 GB memory limits in 
32-bit systems.  The problem should only come up with DB files much 
bigger than this, so that it needs gigs just to store its temporary 
working data.

The open question is what that ratio is, between DB file size and 
working set size.  It is doubtless dependent on the queries you run, and 
probably on other things like indexing.