Documentation Source Text

Check-in [1e3f82a26e]
Login

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

Overview
Comment:Merge in the changes for 3.7.16.2. Update documentation for the mmap_size refactoring.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 1e3f82a26e9a1794161969d0099d2fc8e25519d6
User & Date: drh 2013-04-15 17:13:19.156
Context
2013-04-16
13:09
Added the mmap.html and errlog.html documents. Updates to the "How to Corrupt" document. Update the change log for 3.7.17. (check-in: ccb921fd36 user: drh tags: trunk)
2013-04-15
17:13
Merge in the changes for 3.7.16.2. Update documentation for the mmap_size refactoring. (check-in: 1e3f82a26e user: drh tags: trunk)
13:16
Update the FTS4 document to describe the two-argument form of fts4aux. (check-in: ba14e1152f user: drh tags: trunk)
2013-04-12
12:17
Add sha1sum and source id for version 3.7.16.2 (Leaf check-in: 278390b656 user: dan tags: branch-3.7.16)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/changes.in.
37
38
39
40
41
42
43
44
45
46

47
48
49

50













51
52
53
54
55
56
57
      <a href="http://www.sqlite.org/src/timeline">
      http://www.sqlite.org/src/timeline</a>.</p>
    }
    hd_close_aux
    hd_enable_main 1
  }
}

chng {2013-??-?? (3.7.17)} {
<li>Use of memory mapping to improve I/O performance on windows, linux, and macOS-X.

    This changes includes the [PRAGMA mmap_limit] command, 
    the [sqlite3_config]([SQLITE_CONFIG_MMAP_LIMIT]) start-time configuration
    option, the [SQLITE_DEFAULT_MMAP_LIMIT] compile-time option, and the

    [sqlite3_file_control](db, [SQLITE_FCNTL_MMAP_LIMIT], ...) file-control.













}

chng {2013-03-29 (3.7.16.1)} {
<li>Fix for a bug in the ORDER BY optimizer that was introduced in
    [version 3.7.15] which would sometimes optimize out the sorting step
    when in fact the sort was required.
    Ticket [http://www.sqlite.org/src/info/a179fe7465 | a179fe7465]







<

|
>
|
|
|
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>







37
38
39
40
41
42
43

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
      <a href="http://www.sqlite.org/src/timeline">
      http://www.sqlite.org/src/timeline</a>.</p>
    }
    hd_close_aux
    hd_enable_main 1
  }
}

chng {2013-??-?? (3.7.17)} {
<li>Allow the use of memory mapping to improve I/O performance on windows, linux, 
    and macOS-X.
    This changes includes the [PRAGMA mmap_size] command, 
    the [sqlite3_config]([SQLITE_CONFIG_MMAP_SIZE]) start-time configuration
    option, the [SQLITE_DEFAULT_MMAP_SIZE] and [SQLITE_MAX_MMAP_SIZE]
    compile-time options, and the
    [sqlite3_file_control](db, [SQLITE_FCNTL_MMAP_SIZE], ...) file-control.
}

chng {2012-04-12 (3.7.16.2)} {
<li>Fix a bug (present since version 3.7.13) that could result in database corruption
    on windows if two or more processes try to access the same database file at the
    same time and immediately after third process crashed in the middle of committing
    to that same file.  See ticket 
    [http://www.sqlite.org/src/info/7ff3120e4f | 7ff3120e4f] for further
    information.

<li>SQLITE_SOURCE_ID: 
    "2013-04-12 11:52:43 cbea02d93865ce0e06789db95fd9168ebac970c7"
<li>SHA1 for sqlite3.c: d466b54789dff4fb0238b9232e74896deaefab94
}

chng {2013-03-29 (3.7.16.1)} {
<li>Fix for a bug in the ORDER BY optimizer that was introduced in
    [version 3.7.15] which would sometimes optimize out the sorting step
    when in fact the sort was required.
    Ticket [http://www.sqlite.org/src/info/a179fe7465 | a179fe7465]
Changes to pages/compile.in.
84
85
86
87
88
89
90
91
92

93
94

95
96
97
98
99
100
101
102
103
104
  new database connections.  Each database connection can always turn
  enforcement of foreign key constraints on and off and run-time using
  the [foreign_keys pragma].  Enforcement of foreign key constraints
  is normally off by default, but if this compile-time parameter is
  set to 1, enforcement of foreign key constraints will be on by default.
}

COMPILE_OPTION {SQLITE_DEFAULT_MMAP_LIMIT=<i>N</i>} {
  This macro sets the default maximum number of bytes that will be used

  for memory mapped I/O for each open database file.  If the <i>N</i>
  is zero, then memory mapped I/O is disabled by default.  This

  compile-time limit can be modified at start-time using the
  [sqlite3_config]([SQLITE_CONFIG_MMAP_LIMIT]) call, or at run-time
  using the [mmap_limit pragma].
}

COMPILE_OPTION {SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<i>&lt;bytes&gt;</i>} {
  This option sets the size limit on [rollback journal] files in
  [journal_mode pragma | persistent journal mode] and
  [locking_mode | exclusive locking mode] and on the size of the
  write-ahead log file in [WAL mode]. When this 







|
|
>
|

>
|
|
|







84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
  new database connections.  Each database connection can always turn
  enforcement of foreign key constraints on and off and run-time using
  the [foreign_keys pragma].  Enforcement of foreign key constraints
  is normally off by default, but if this compile-time parameter is
  set to 1, enforcement of foreign key constraints will be on by default.
}

COMPILE_OPTION {SQLITE_DEFAULT_MMAP_SIZE=<i>N</i>} {
  This macro sets the default limit on the amount of memory that
  will be used for memory-mapped I/O
  for each open database file.  If the <i>N</i>
  is zero, then memory mapped I/O is disabled by default.  This
  compile-time limit and the [SQLITE_MAX_MMAP_SIZE] can be modified 
  at start-time using the
  [sqlite3_config]([SQLITE_CONFIG_MMAP_SIZE]) call, or at run-time
  using the [mmap_size pragma].
}

COMPILE_OPTION {SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<i>&lt;bytes&gt;</i>} {
  This option sets the size limit on [rollback journal] files in
  [journal_mode pragma | persistent journal mode] and
  [locking_mode | exclusive locking mode] and on the size of the
  write-ahead log file in [WAL mode]. When this 
136
137
138
139
140
141
142














143
144
145
146
147
148
149
}

COMPILE_OPTION {SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<i>&lt;pages&gt;</i>} {
  This macro sets the default page count for the [WAL]
  [checkpointing | automatic checkpointing] feature.  If unspecified,
  the default page count is 1000.
}















COMPILE_OPTION {SQLITE_MAX_SCHEMA_RETRY=<i>N</i>} {
  Whenever the database schema changes, prepared statements are automatically
  reprepared to accommodate the new schema.  There is a race condition here
  in that if one thread is constantly changing the schema, another thread
  might spin on reparses and repreparations of a prepared statement and
  never get any real work done.  This parameter prevents an infinite loop







>
>
>
>
>
>
>
>
>
>
>
>
>
>







138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
}

COMPILE_OPTION {SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<i>&lt;pages&gt;</i>} {
  This macro sets the default page count for the [WAL]
  [checkpointing | automatic checkpointing] feature.  If unspecified,
  the default page count is 1000.
}

COMPILE_OPTION {SQLITE_MAX_MMAP_SIZE=<i>N</i>} {
  This macro sets a hard upper bound on the amount of address space that
  can be used by any single database for memory-mapped I/O.
  Setting this value to 0 completely disables memory-mapped I/O and
  causes logic associated with memory-mapped I/O to be omitted from the
  build.  This option does change the default memory-mapped I/O address
  space size (set by [SQLITE_DEFAULT_MMAP_SIZE] or
  sqlite3_config([SQLITE_CONFIG_MMAP_SIZE])) or the
  run-time memory-mapped I/O address space size (set by
  sqlite3_file_control([SQLITE_FCNTL_MMAP_SIZE])) or
  [PRAGMA mmap_size]) as long as those other settings are less than the
  maximum value defined here.
}

COMPILE_OPTION {SQLITE_MAX_SCHEMA_RETRY=<i>N</i>} {
  Whenever the database schema changes, prepared statements are automatically
  reprepared to accommodate the new schema.  There is a race condition here
  in that if one thread is constantly changing the schema, another thread
  might spin on reparses and repreparations of a prepared statement and
  never get any real work done.  This parameter prevents an infinite loop
Changes to pages/index.in.
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_7_17.html">Version 3.7.17</a>
of SQLite is recommended for all new development.
Upgrading from version 3.7.16.1 is optional.
Upgrading from all other SQLite versions
is recommended.</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>







|







93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_7_17.html">Version 3.7.17</a>
of SQLite is recommended for all new development.
Upgrading from version 3.7.16.2 is optional.
Upgrading from all other SQLite versions
is recommended.</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>
Changes to pages/news.in.
14
15
16
17
18
19
20




















21
22
23
24
25
26
27
  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}





















newsitem {2013-03-29} {Release 3.7.16.1} {
  SQLite [version 3.7.16.1] is a bug fix release that fixes a few problems
  that were present in the previous releases.

  The primary motivation for version 3.7.16.1 is to fix a bug in the
  query optimizer that was introduced as part of [version 3.7.15].  The







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}

newsitem {2013-04-12} {Release 3.7.16.2} {
  SQLite [version 3.7.16.2] fixes a long-standing flaw in the Windows
  OS interface that
  can result in database corruption under a rare race condition.
  See [http://www.sqlite.org/src/info/7ff3120e4f] for a full description
  of the problem.

  As far as we know, this bug has never been seen in the wild.  The
  problem was discovered by the SQLite developers while writing stress tests
  for a separate component of SQLite.  Those stress tests have not yet
  found any problems with the component they were intended to verify, but 
  they did find the bug which is the subject of this patch release.

  Other than updates to version numbers, the only difference between this
  release and 3.7.16.1 is a two-character change in a single identifier,
  which is contained in the windows-specific OS interface logic.  There 
  are no changes in this release (other than version numbers) for platforms
  other than Windows.
}

newsitem {2013-03-29} {Release 3.7.16.1} {
  SQLite [version 3.7.16.1] is a bug fix release that fixes a few problems
  that were present in the previous releases.

  The primary motivation for version 3.7.16.1 is to fix a bug in the
  query optimizer that was introduced as part of [version 3.7.15].  The
Changes to pages/pragma.in.
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649






650
651
652
653
654
655
656
   NORMAL until after exiting WAL journal mode. 
   ^If the locking mode is NORMAL when first entering WAL
   journal mode, then the locking mode can be changed between NORMAL and
   EXCLUSIVE and back again at any time and without needing to exit
   WAL journal mode.</p>
}

Pragma mmap_limit {
    <p>^(<br><b>PRAGMA </b><i>database</i><b>.mmap_limit;
         <br>PRAGMA </b><i>database</i><b>.mmap_limit=</b><i>N</i></p>

    <p>Query or change the maximum number of bytes that are set
       aside for memory-mapped I/O on a single database.  The first form
       (without an argument) queries the current limit.  The second
       form (with a numeric argument) sets the limit for the specified
       database, or for all databases if the optional database name is
       omitted.  In the second form, if the database name is omitted, the
       limit that is set becomes the default limit for all databases that
       are added to the [database connection] by subsequent [ATTACH]
       statements.</p>

    <p>The argument N is the maximum number of bytes of the database file
       that will be accessed using memory-mapped I/O.  If N is zero then
       memory mapped I/O is disabled.  If N is negative, then the limit
       reverts to the default value determined by the most recent
       [sqlite3_config]([SQLITE_CONFIG_MMAP_LIMIT]), or to the compile
       time default determined by [SQLITE_DEFAULT_MMAP_LIMIT] if not
       start-time limit has been set.</p>






}

Pragma page_size {
   <p>^(<b>PRAGMA page_size;
       <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p>
    <p>Query or set the page size of the database.)^ ^The page
    size must be a power of two between 512 and 65536 inclusive.







|
|
|















|
|

>
>
>
>
>
>







622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
   NORMAL until after exiting WAL journal mode. 
   ^If the locking mode is NORMAL when first entering WAL
   journal mode, then the locking mode can be changed between NORMAL and
   EXCLUSIVE and back again at any time and without needing to exit
   WAL journal mode.</p>
}

Pragma mmap_size {
    <p>^(<br><b>PRAGMA </b><i>database</i><b>.mmap_size;
         <br>PRAGMA </b><i>database</i><b>.mmap_size=</b><i>N</i></p>

    <p>Query or change the maximum number of bytes that are set
       aside for memory-mapped I/O on a single database.  The first form
       (without an argument) queries the current limit.  The second
       form (with a numeric argument) sets the limit for the specified
       database, or for all databases if the optional database name is
       omitted.  In the second form, if the database name is omitted, the
       limit that is set becomes the default limit for all databases that
       are added to the [database connection] by subsequent [ATTACH]
       statements.</p>

    <p>The argument N is the maximum number of bytes of the database file
       that will be accessed using memory-mapped I/O.  If N is zero then
       memory mapped I/O is disabled.  If N is negative, then the limit
       reverts to the default value determined by the most recent
       [sqlite3_config]([SQLITE_CONFIG_MMAP_SIZE]), or to the compile
       time default determined by [SQLITE_DEFAULT_MMAP_SIZE] if not
       start-time limit has been set.</p>

    <p>The [PRAGMA mmap_size] statement will never increase the amount
       of address space used for memory-mapped I/O above the
       hard limit set by the [SQLITE_MAX_MMAP_SIZE] compile-time option,
       nor the hard limit set start-time by the second argument to
       sqlite3_config([SQLITE_CONFIG_MMAP_SIZE])</p>
}

Pragma page_size {
   <p>^(<b>PRAGMA page_size;
       <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p>
    <p>Query or set the page size of the database.)^ ^The page
    size must be a power of two between 512 and 65536 inclusive.