2
2
# Run this Tcl script to generate the pragma.html file.
4
set rcsid {$Id: pragma.tcl,v 1.20 2007/02/02 12:33:17 drh Exp $}
4
set rcsid {$Id: pragma.tcl,v 1.22 2007/04/02 00:53:19 drh Exp $}
6
6
header {Pragma statements supported by SQLite}
27
27
Unknown pragmas are simply ignored. This means if there is a typo in
28
28
a pragma statement the library does not inform the user of the fact.
29
29
<li>Some pragmas take effect during the SQL compilation stage, not the
30
execution stage. This means if using the C-language sqlite3_compile(),
30
execution stage. This means if using the C-language sqlite3_prepare(),
31
31
sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper
32
32
interface), the pragma may be applied to the library during the
33
sqlite3_compile() call.
33
sqlite3_prepare() call.
34
34
<li>The pragma command is unlikely to be compatible with any other SQL
38
38
<p>The available pragmas fall into four basic categories:</p>
40
<li>Pragmas used to <a href="#schema">query the schema</a> of the current
42
40
<li>Pragmas used to <a href="#modify">modify the operation</a> of the
43
41
SQLite library in some manner, or to query for the current mode of
43
<li>Pragmas used to <a href="#schema">query the schema</a> of the current
45
45
<li>Pragmas used to <a href="#version">query or modify the databases two
46
46
version values</a>, the schema-version and the user-version.
47
47
<li>Pragmas used to <a href="#debug">debug the library</a> and verify that
235
235
effect on databases that already exist.</p>
238
<a name="pragma_locking_mode"></a>
239
<li><p><b>PRAGMA locking_mode;
240
<br>PRAGMA locking_mode = <i>NORMAL | EXCLUSIVE</i></b></p>
241
<p>This pragma sets or queries the database connection locking-mode.
242
The locking-mode is either NORMAL or EXCLUSIVE.
244
<p>In NORMAL locking-mode (the default), a database connection
245
unlocks the database file at the conclusion of each read or
246
write transaction. When the locking-mode is set to EXCLUSIVE, the
247
database connection never releases file-locks. The first time the
248
database is read in EXCLUSIVE mode, a shared lock is obtained and
249
held. The first time the database is written, an exclusive lock is
250
obtained and held.</p>
252
<p>Database locks obtained by a connection in EXCLUSIVE mode may be
253
released either by closing the database connection, or by setting the
254
locking-mode back to NORMAL using this pragma and then accessing the
255
database file (for read or write). Simply setting the locking-mode to
256
NORMAL is not enough - locks are not be released until the next time
257
the database file is accessed.</p>
259
<p>There are two reasons to set the locking-mode to EXCLUSIVE. One
260
is if the application actually wants to prevent other processes from
261
accessing the database file. The other is that a small number of
262
filesystem operations are saved by optimizations enabled in this
263
mode. This may be significant in embedded environments.</p>
265
<p>When the locking_mode pragma specifies a particular database,
269
PRAGMA <b>main.</b>locking_mode=EXCLUSIVE;
272
<p>Then the locking mode applies only to the named database. If no
273
database name qualifier preceeds the "locking_mode" keyword then
274
the locking mode is applied to all databases, including any new
275
databases added by subsequent <a href="lang_attach.html">ATTACH</a>
278
<p>The "temp" database (in which TEMP tables and indices are stored)
279
always uses exclusive locking mode. The locking mode of temp cannot
280
be changed. All other databases use the normal locking mode by default
281
and are effected by this pragma.</p>
239
284
<a name="pragma_page_size"></a>
240
285
<li><p><b>PRAGMA page_size;