Documentation Source Text

chng {2011 June 28 (3.7.7)} {
<li> Add support for [URI filenames]
<li> Add support for [ON CONFLICT] clauses with [virtual tables].
<li> Avoid unnecessary reparsing of the database schema.
<li> Allow [WAL | WAL-mode] databases to be opened read-only as long as
     there is an existing read/write connection.
<li> Added support for [short filenames].


}

chng {2011 April 17 (3.7.6.2)} {
<li> Fix the function prototype for the open(2) system call to agree with
     POSIX.  Without this fix, pthreads does not work correctly on NetBSD.
<li> SQLITE_SOURCE_ID:
     "2011-04-17 17:25:17 154ddbc17120be2915eb03edc52af1225eb7cb5e"

is to make use of the [backup API] that is part of the SQLite library.
Failing that, it is safe to make a copy of an SQLite database file as long
as there are no transactions in progress by any process.  If the previous
transaction failed, then it is important that any rollback journal
(the <tt>*-journal</tt> file) or write-ahead log (the <tt>*-wal</tt> file)
be copied together with the database file itself.</p>

<tcl>hd_fragment delhotjrnl {deleting a hot journal}</tcl>
<h3>1.3 Deleting a hot journal</h3>

<p>SQLite normally stores all content in a single disk file.  However,
while performing a transaction, information necessary to roll back that
transaction following a crash or power failure is stored in auxiliary
journal files.  These journal files have the same name as the
original database file with the addition
of <tt>-journal</tt> or <tt>-wal</tt> suffix.</p>

<p>SQLite must see the journal files in order to recover from a crash
or power failure.  If the journal files are moved, deleted, or renamed
after a crash or power failure, then automatic recovery will not work
and the database may go corrupt.</p>

<p>Another manifestation of this problem is
[database corruption caused by inconsistent use of 8+3 filenames].</p>

<h2>2.0 File locking problems</h2>

<p>SQLite uses file locks on the database file, and on the 
[write-ahead log] or [WAL] file, to coordinate access between concurrent
processes.  Without coordination, two threads or processes might try
to make incompatible changes to a database file at the same time,
resulting in database corruption.</p>

<h2>Changing Filesystems</h2>

<p>
The recommended fix for this problem is to select a different
filesystem.  These days, there is a huge selection of high-performance, 
reliable, patent-free filesystems that support long filenames.  
Where possible, it is recommended that embedded devices use one
of these other filesystems.  This will avoid compatibility issues
and the danger of
[database corruption caused by inconsistent use of 8+3 filenames].
</p>

<h2>Adjusting SQLite To Use 8+3 Filenames</h2>

<p>
Some systems are compelled to use an older filesystem with 8+3
filename restructions in order to be compatible with legacy, or due

of extension.  If there is no extension, then SQLite creates auxiliary
filenames by appending to the base name of the file.  Thus, a database
named "<tt>db01</tt>" would have a [rollback journal] file named
"<tt>db01-journal</tt>".  And as this filename has no extension to shorten
to 3 characters, it will be used as-is, and will violate 8+3 naming rules.
</p>

<tcl>hd_fragment db83corrupt \
   {database corruption caused by inconsistent use of 8+3 filenames}
</tcl>
<h2>Database Corruption Warning</h2>

<p>
If a database file is accessed using 8+3 naming rather than the default
long filename, then it must be consistently accessed 
using 8+3 naming by every database
connection every time it is opened, or else there is a risk of database
corruption.
The auxiliary [rollback journal] and [write-ahead log] files are essential
to SQLite for being about to recover from a crash.  If an application is
using 8+3 names and crashes, then the information needed to safely recover
from the crash is stored in files with the "<tt>.nal</tt>" or
"<tt>.wal</tt>" extension.  If the next application to open the database
does not specify the "<tt>8_3_names=1</tt>" URI parameter, then SQLite
will use the long filenames to try to locate the rollback journal or
write-ahead log files.  It will not find them, since they were saved using
8+3 names by the application that crashed, and hence the database will not
be properly recovered and will likely go corrupt.
</p>

<p>
Using a database file with 8+3 filenames in some cases while in 
other cases using long filenames is equivalent to
[deleting a hot journal].
</p>