Documentation Source Text

Check-in [d545903147]
Login

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

Overview
Comment:Merge changes from the 3.12 branch.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: d5459031474dc22d83db22b2e29787e4bb4b66bf
User & Date: drh 2016-05-05 13:33:42.062
Context
2016-05-05
23:40
Add sub-bullets in the description of the b-tree page type flag in fileformat2.html, for improved legibility. (check-in: ff214d6ba0 user: drh tags: trunk)
13:33
Merge changes from the 3.12 branch. (check-in: d545903147 user: drh tags: trunk)
13:28
Clarify that using an database file with a link count different from 1 results in undefined behavior. (Leaf check-in: 7c96132d65 user: drh tags: branch-3.12)
2016-05-04
11:46
Fix typos in the change log. (check-in: 05caaf5dfb user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/howtocorrupt.in.
188
189
190
191
192
193
194
195
196
197
198
199



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214



215
216
217
218
219





220
221
222
223
224
225
226
then the two processes will be talking to different database files with 
the same name.  (Note that this is only possible on Posix and Posix-like
systems that permit a file to be unlinked while it is still open for
reading and writing.  Windows does not allow this to occur.)
Since rollback journals and WAL files are based on the name of the database
file, the two different database files will share the same rollback
journal or WAL file.  A rollback or recovery for one of the databases
might use content from the other database, resulting in corruption.</p>

<p>A similar problem occurs if a database file is renamed while it is
opened and a new file is created with the old name.</p>




<p>Beginning with SQLite [version 3.7.17], the unix OS interface will
send SQLITE_WARNING messages to the [error log] if a database file is unlinked
while it is still in use.</p>

<tcl>hd_fragment alias {database filename aliasing}</tcl>
<h3>2.5 Multiple links to the same file</h3>

<p>If a single database file has multiple links (either hard or soft links)
then that is just another way of saying that the file has multiple names.
If two or more processes open the database using different names, then
they will use different rollback journals and WAL files.  That means that
if one process crashes, the other process will be unable to recover the
transaction in progress because it will be looking in the wrong place
for the appropriate journal.</p>




<p>Beginning with SQLite [version 3.7.17], the unix OS interface will
send SQLITE_WARNING messages to the [error log] if a database file has 
multiple hard links.  As of this writing, SQLite still does not yet detect 
or warn about the use of database files through soft links.</p>







<h2>3.0 Failure to sync</h2>

<p>In order to guarantee that database files are always consistent, SQLite
will occasionally ask the operating system to flush all pending writes to
persistent storage then wait for that flush to complete.  This is 
accomplished using the <tt>fsync()</tt> system call under unix and







|
<
|


>
>
>















>
>
>


|
<

>
>
>
>
>







188
189
190
191
192
193
194
195

196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222

223
224
225
226
227
228
229
230
231
232
233
234
235
then the two processes will be talking to different database files with 
the same name.  (Note that this is only possible on Posix and Posix-like
systems that permit a file to be unlinked while it is still open for
reading and writing.  Windows does not allow this to occur.)
Since rollback journals and WAL files are based on the name of the database
file, the two different database files will share the same rollback
journal or WAL file.  A rollback or recovery for one of the databases
might use content from the other database, resulting in corruption.

A similar problem occurs if a database file is renamed while it is
opened and a new file is created with the old name.</p>

<p>In other words, unlinking or renaming an open database file 
results in behavior that is undefined and probably undesirable.</p>

<p>Beginning with SQLite [version 3.7.17], the unix OS interface will
send SQLITE_WARNING messages to the [error log] if a database file is unlinked
while it is still in use.</p>

<tcl>hd_fragment alias {database filename aliasing}</tcl>
<h3>2.5 Multiple links to the same file</h3>

<p>If a single database file has multiple links (either hard or soft links)
then that is just another way of saying that the file has multiple names.
If two or more processes open the database using different names, then
they will use different rollback journals and WAL files.  That means that
if one process crashes, the other process will be unable to recover the
transaction in progress because it will be looking in the wrong place
for the appropriate journal.</p>

<p>In other words, opening and using a database file that has two or
more names results in behavior that is undefined and probably undesirable.</p>

<p>Beginning with SQLite [version 3.7.17], the unix OS interface will
send SQLITE_WARNING messages to the [error log] if a database file has 
multiple hard links.</p>


<p>Beginning with SQLite [version 3.10.0], the unix OS interface will
attempt to resolve symbolic links and open the database file by its
canonical name.  Prior to version 3.10.0, opening a database file 
through a symbolic link was similar to opening a database file
that had multiple hard links and resulted in undefined behavior.</p>

<h2>3.0 Failure to sync</h2>

<p>In order to guarantee that database files are always consistent, SQLite
will occasionally ask the operating system to flush all pending writes to
persistent storage then wait for that flush to complete.  This is 
accomplished using the <tt>fsync()</tt> system call under unix and
Changes to pages/pragma.in.
798
799
800
801
802
803
804
805

806
807
808
809
810
811
812
813
    <p>^When a new database is created, SQLite assigned a page size to
    the database based on platform and filesystem.  For many years,
    the default page size was almost always 1024 bytes, but beginning
    with SQLite [version 3.12.0] in 2016, the default page size increased
    to 4096.

    <p>^The page_size pragma will only cause an immediate change in the
    page size if it is issued while the database is still empty, prior 

    to the first CREATE TABLE statement.  ^(If the page_size pragma is
    used to specify a new page size just prior to
    running the [VACUUM] command and if the database is not in
    [WAL | WAL journal mode] then [VACUUM] will change the page
    size to the new value.)^</p>

    <p>^The [SQLITE_DEFAULT_PAGE_SIZE] compile-time option can be used
    to change the default page size assigned to new databases.







|
>
|







798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
    <p>^When a new database is created, SQLite assigned a page size to
    the database based on platform and filesystem.  For many years,
    the default page size was almost always 1024 bytes, but beginning
    with SQLite [version 3.12.0] in 2016, the default page size increased
    to 4096.

    <p>^The page_size pragma will only cause an immediate change in the
    page size if it is issued while the database is still empty (prior 
    to the first CREATE statement) and if the database is not in
    [WAL mode].  ^(If the page_size pragma is
    used to specify a new page size just prior to
    running the [VACUUM] command and if the database is not in
    [WAL | WAL journal mode] then [VACUUM] will change the page
    size to the new value.)^</p>

    <p>^The [SQLITE_DEFAULT_PAGE_SIZE] compile-time option can be used
    to change the default page size assigned to new databases.