Documentation Source Text

Check-in [7aa71cbb0c]
Login

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

Overview
Comment:Add notes on the SQLITE_IOCAP_IMMUTABLE and "nolock" and "immutable" query parameter changes.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 7aa71cbb0c800bb295816d1abee16515052679ec
User & Date: drh 2014-05-07 16:00:35
Context
2014-05-09
22:27
Fix typo in VALUES clause documentation in lang.html. check-in: fee01c2d5b user: drh tags: trunk
2014-05-07
16:00
Add notes on the SQLITE_IOCAP_IMMUTABLE and "nolock" and "immutable" query parameter changes. check-in: 7aa71cbb0c user: drh tags: trunk
2014-05-01
14:44
Updates to the R*Tree documentation. check-in: bd0fe1c3e1 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

21
22
23
24
25
26
27



28
29
30
31
32
33
34
35
chng {2014-06-?? (3.8.5)} {
<li>Added support for sorting subsets of the result when the result comes out of the query
    engine already partially sorted.
<li>Enhance the query planner so that it always prefers an index that uses a superset of
    WHERE clause terms relative to some other index.
<li>Added the [SQLITE_TESTCTRL_BYTEORDER] test control.
<li>Added the [sqlite3_rtree_query_callback()] interface to [R-Tree extension]



<p><b>Bug Fixes:</b>
<li>OFFSET clause ignored on queries without a FROM clause.
    Ticket [http://www.sqlite.org/src/info/07d6a0453d | 07d6a0453d]
<li>Assertion fault on queries involving expressions of the form
    "x IN (?)".  Ticket [http://www.sqlite.org/src/info/e39d032577|e39d032577].
<li>Incorrect column datatype reported.
    Ticket [http://www.sqlite.org/src/info/a8a0d2996a | a8a0d2996a]
<li>Duplicate row returned on a query against a table with more than







>
>
>
|







21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
chng {2014-06-?? (3.8.5)} {
<li>Added support for sorting subsets of the result when the result comes out of the query
    engine already partially sorted.
<li>Enhance the query planner so that it always prefers an index that uses a superset of
    WHERE clause terms relative to some other index.
<li>Added the [SQLITE_TESTCTRL_BYTEORDER] test control.
<li>Added the [sqlite3_rtree_query_callback()] interface to [R-Tree extension]
<li>Added the [SQLITE_IOCAP_IMMUTABLE] bit to the set of bits that can be returned by
    the xDeviceCharacteristics method of a [VFS].
<li>Added new [URI query parameters] "nolock" and "immutable".
query<p><b>Bug Fixes:</b>
<li>OFFSET clause ignored on queries without a FROM clause.
    Ticket [http://www.sqlite.org/src/info/07d6a0453d | 07d6a0453d]
<li>Assertion fault on queries involving expressions of the form
    "x IN (?)".  Ticket [http://www.sqlite.org/src/info/e39d032577|e39d032577].
<li>Incorrect column datatype reported.
    Ticket [http://www.sqlite.org/src/info/a8a0d2996a | a8a0d2996a]
<li>Duplicate row returned on a query against a table with more than

Changes to pages/uri.in.

155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

179
180
181
182
183
184
185

186
187
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
the first query parameters, each key and value, and each subsequent key
from the prior value.
^The list of query parameters parameters appended to the xOpen filename
is terminated by a single zero-length key.
Note that the value of a query parameter can be an empty string.
</p>

<tcl>hd_fragment coreqp *coreqp\
    {query parameters with special meaning to SQLite}</tcl>
<h2>3.3 Recognized Query Parameters</h2>

<p>
Some query parameters are interpreted by the SQLite core and used to 
modify the characteristics of the new connection.  ^All query parameters
are always passed through into the xOpen method of the [VFS] even if
they are previously read and interpreted by the SQLite core.
</p>

<p>
The following query parameters are recognized by SQLite as of version 3.7.10.
Other query parameters might be added to this set in future releases.
</p>

<dl>

<dt><b>vfs=</b><i>NAME</i></dt>
<dd><p>^The vfs query parameter causes the database connection to be opened
using the [VFS] called <i>NAME</i>.
^The open attempt fails if <i>NAME</i> is not the name of a [VFS] that
is built into SQLite or that has been previously registered using
[sqlite3_vfs_register()].</dd>


<dt><b>mode=ro<br>mode=rw<br>mode=rwc<br>mode=memory</b></dt>
<dd><p>^The mode query parameter determines if the new database is opened
read-only, read-write, read-write and created if it does not exist, or
that the database is a pure in-memory database that never interacts with
disk, respectively.  The <b>mode=memory</b> option was added in 
[version 3.7.13].
</dd>


<dt><b>cache=shared<br>cache=private</b></dt>
<dd><p>^The cache query parameter determines if the new database is opened
using [shared cache mode] or with a private cache.
</dd>


<dt><b>psow=0<br>psow=1</b></dt>
<dd><p>^The psow query parameter overrides the [powersafe overwrite]
property of the database file being opened.  ^The psow query parameter
works with the default windows and unix [VFSes] but might be a no-op for
other proprietary or non-standard VFSes.
</dd>



























</dl>

<h1>4.0 See Also</h1>

<ul>
<li> [URI filenames in sqlite3_open()]
<li> [URI filename examples]
</ul>







|











|




>







>




|
<


>





>






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








155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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
236
237
238
239
240
241
242
the first query parameters, each key and value, and each subsequent key
from the prior value.
^The list of query parameters parameters appended to the xOpen filename
is terminated by a single zero-length key.
Note that the value of a query parameter can be an empty string.
</p>

<tcl>hd_fragment coreqp *coreqp {standard query parameters} {URI query parameters} \
    {query parameters with special meaning to SQLite}</tcl>
<h2>3.3 Recognized Query Parameters</h2>

<p>
Some query parameters are interpreted by the SQLite core and used to 
modify the characteristics of the new connection.  ^All query parameters
are always passed through into the xOpen method of the [VFS] even if
they are previously read and interpreted by the SQLite core.
</p>

<p>
The following query parameters are recognized by SQLite as of version 3.8.0.
Other query parameters might be added to this set in future releases.
</p>

<dl>
<tcl>hd_fragment urivfs {"vfs" query parameter}</tcl>
<dt><b>vfs=</b><i>NAME</i></dt>
<dd><p>^The vfs query parameter causes the database connection to be opened
using the [VFS] called <i>NAME</i>.
^The open attempt fails if <i>NAME</i> is not the name of a [VFS] that
is built into SQLite or that has been previously registered using
[sqlite3_vfs_register()].</dd>

<tcl>hd_fragment urimode {"mode" query parameter}</tcl>
<dt><b>mode=ro<br>mode=rw<br>mode=rwc<br>mode=memory</b></dt>
<dd><p>^The mode query parameter determines if the new database is opened
read-only, read-write, read-write and created if it does not exist, or
that the database is a pure in-memory database that never interacts with
disk, respectively.

</dd>

<tcl>hd_fragment uricache {"cache" query parameter}</tcl>
<dt><b>cache=shared<br>cache=private</b></dt>
<dd><p>^The cache query parameter determines if the new database is opened
using [shared cache mode] or with a private cache.
</dd>

<tcl>hd_fragment uripsow {"psow" query parameter}</tcl>
<dt><b>psow=0<br>psow=1</b></dt>
<dd><p>^The psow query parameter overrides the [powersafe overwrite]
property of the database file being opened.  ^The psow query parameter
works with the default windows and unix [VFSes] but might be a no-op for
other proprietary or non-standard VFSes.
</dd>

<tcl>hd_fragment urinolock {"nolock" query parameter}</tcl>
<dt><b>nolock=1</b></dt>
<dd><p>^The nolock query parameter is a boolean that disables all calls
to the xLock, xUnlock, and xCheckReservedLock methods of the VFS when true.
The nolock query parameter might be used, for example, when trying to
access a file on a filesystem that does not support file locking.
Caution:  If two or more [database connections] try to interact with 
the same SQLite database and one or more of those connections has
enabled "nolock", then database corruption can result.  The "nolock"
query parameter should only be used if the application can guarantee
that writes to the database are serialized.
</dd>

<tcl>hd_fragment uriimmutable {"immutable" query parameter}</tcl>
<dt><b>immutable=1</b></dt>
<dd><p>^The immutable query parameter is a boolean that signals to
SQLite that the underlying database file is held on read-only media
and cannot be modified, even by another process with elevated 
privileges.  ^SQLite always opens immutable database files
read-only and it skips all file locking and change detection
on immutable database files.  If these query parameter (or
the [SQLITE_IOCAP_IMMUTABLE] bit in xDeviceCharacteristics)
asserts that a database file is immutable and that file 
changes anyhow, then SQLite might return incorrect query 
results and/or [SQLITE_CORRUPT] errors.
</dd>
</dl>

<h1>4.0 See Also</h1>

<ul>
<li> [URI filenames in sqlite3_open()]
<li> [URI filename examples]
</ul>