| 1 |
<!DOCTYPE html> |
| 2 |
<html><head> |
| 3 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 4 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 5 |
<link href="../sqlite.css" rel="stylesheet"> |
| 6 |
<title>Database Connection Configuration Options</title> |
| 7 |
<!-- path=../ --> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
<div class=nosearch> |
| 11 |
<a href="../index.html"> |
| 12 |
<img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0"> |
| 13 |
</a> |
| 14 |
<div><!-- IE hack to prevent disappearing logo --></div> |
| 15 |
<div class="tagline desktoponly"> |
| 16 |
Small. Fast. Reliable.<br>Choose any three. |
| 17 |
</div> |
| 18 |
<div class="menu mainmenu"> |
| 19 |
<ul> |
| 20 |
<li><a href="../index.html">Home</a> |
| 21 |
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> |
| 22 |
<li class='wideonly'><a href='../about.html'>About</a> |
| 23 |
<li class='desktoponly'><a href="../docs.html">Documentation</a> |
| 24 |
<li class='desktoponly'><a href="../download.html">Download</a> |
| 25 |
<li class='wideonly'><a href='../copyright.html'>License</a> |
| 26 |
<li class='desktoponly'><a href="../support.html">Support</a> |
| 27 |
<li class='desktoponly'><a href="../prosupport.html">Purchase</a> |
| 28 |
<li class='search' id='search_menubutton'> |
| 29 |
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> |
| 30 |
</ul> |
| 31 |
</div> |
| 32 |
<div class="menu submenu" id="submenu"> |
| 33 |
<ul> |
| 34 |
<li><a href='../about.html'>About</a> |
| 35 |
<li><a href='../docs.html'>Documentation</a> |
| 36 |
<li><a href='../download.html'>Download</a> |
| 37 |
<li><a href='../support.html'>Support</a> |
| 38 |
<li><a href='../prosupport.html'>Purchase</a> |
| 39 |
</ul> |
| 40 |
</div> |
| 41 |
<div class="searchmenu" id="searchmenu"> |
| 42 |
<form method="GET" action="../search"> |
| 43 |
<select name="s" id="searchtype"> |
| 44 |
<option value="d">Search Documentation</option> |
| 45 |
<option value="c">Search Changelog</option> |
| 46 |
</select> |
| 47 |
<input type="text" name="q" id="searchbox" value=""> |
| 48 |
<input type="submit" value="Go"> |
| 49 |
</form> |
| 50 |
</div> |
| 51 |
</div> |
| 52 |
<script> |
| 53 |
function toggle_div(nm) { |
| 54 |
var w = document.getElementById(nm); |
| 55 |
if( w.style.display=="block" ){ |
| 56 |
w.style.display = "none"; |
| 57 |
}else{ |
| 58 |
w.style.display = "block"; |
| 59 |
} |
| 60 |
} |
| 61 |
function toggle_search() { |
| 62 |
var w = document.getElementById("searchmenu"); |
| 63 |
if( w.style.display=="block" ){ |
| 64 |
w.style.display = "none"; |
| 65 |
} else { |
| 66 |
w.style.display = "block"; |
| 67 |
setTimeout(function(){ |
| 68 |
document.getElementById("searchbox").focus() |
| 69 |
}, 30); |
| 70 |
} |
| 71 |
} |
| 72 |
function div_off(nm){document.getElementById(nm).style.display="none";} |
| 73 |
window.onbeforeunload = function(e){div_off("submenu");} |
| 74 |
/* Disable the Search feature if we are not operating from CGI, since */ |
| 75 |
/* Search is accomplished using CGI and will not work without it. */ |
| 76 |
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ |
| 77 |
document.getElementById("search_menubutton").style.display = "none"; |
| 78 |
} |
| 79 |
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ |
| 80 |
function hideorshow(btn,obj){ |
| 81 |
var x = document.getElementById(obj); |
| 82 |
var b = document.getElementById(btn); |
| 83 |
if( x.style.display!='none' ){ |
| 84 |
x.style.display = 'none'; |
| 85 |
b.innerHTML='show'; |
| 86 |
}else{ |
| 87 |
x.style.display = ''; |
| 88 |
b.innerHTML='hide'; |
| 89 |
} |
| 90 |
return false; |
| 91 |
} |
| 92 |
var antiRobot = 0; |
| 93 |
function antiRobotGo(){ |
| 94 |
if( antiRobot!=3 ) return; |
| 95 |
antiRobot = 7; |
| 96 |
var j = document.getElementById("mtimelink"); |
| 97 |
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); |
| 98 |
} |
| 99 |
function antiRobotDefense(){ |
| 100 |
document.body.onmousedown=function(){ |
| 101 |
antiRobot |= 2; |
| 102 |
antiRobotGo(); |
| 103 |
document.body.onmousedown=null; |
| 104 |
} |
| 105 |
document.body.onmousemove=function(){ |
| 106 |
antiRobot |= 2; |
| 107 |
antiRobotGo(); |
| 108 |
document.body.onmousemove=null; |
| 109 |
} |
| 110 |
setTimeout(function(){ |
| 111 |
antiRobot |= 1; |
| 112 |
antiRobotGo(); |
| 113 |
}, 100) |
| 114 |
antiRobotGo(); |
| 115 |
} |
| 116 |
antiRobotDefense(); |
| 117 |
</script> |
| 118 |
<!-- keywords: SQLITE_DBCONFIG_DEFENSIVE SQLITE_DBCONFIG_DQS_DDL SQLITE_DBCONFIG_DQS_DML SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE SQLITE_DBCONFIG_ENABLE_COMMENTS SQLITE_DBCONFIG_ENABLE_FKEY SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION SQLITE_DBCONFIG_ENABLE_QPSG SQLITE_DBCONFIG_ENABLE_TRIGGER SQLITE_DBCONFIG_ENABLE_VIEW SQLITE_DBCONFIG_FP_DIGITS SQLITE_DBCONFIG_LEGACY_ALTER_TABLE SQLITE_DBCONFIG_LEGACY_FILE_FORMAT SQLITE_DBCONFIG_LOOKASIDE SQLITE_DBCONFIG_MAINDBNAME SQLITE_DBCONFIG_MAX SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE SQLITE_DBCONFIG_RESET_DATABASE SQLITE_DBCONFIG_REVERSE_SCANORDER SQLITE_DBCONFIG_STMT_SCANSTATUS SQLITE_DBCONFIG_TRIGGER_EQP SQLITE_DBCONFIG_TRUSTED_SCHEMA SQLITE_DBCONFIG_WRITABLE_SCHEMA --> |
| 119 |
<div class=nosearch> |
| 120 |
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a> |
| 121 |
<h2>Database Connection Configuration Options</h2> |
| 122 |
</div> |
| 123 |
<blockquote><pre> |
| 124 |
#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ |
| 125 |
#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ |
| 126 |
#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ |
| 127 |
#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ |
| 128 |
#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ |
| 129 |
#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ |
| 130 |
#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ |
| 131 |
#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ |
| 132 |
#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ |
| 133 |
#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ |
| 134 |
#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ |
| 135 |
#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ |
| 136 |
#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ |
| 137 |
#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ |
| 138 |
#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ |
| 139 |
#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */ |
| 140 |
#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */ |
| 141 |
#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */ |
| 142 |
#define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */ |
| 143 |
#define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */ |
| 144 |
#define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE 1020 /* int int* */ |
| 145 |
#define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE 1021 /* int int* */ |
| 146 |
#define SQLITE_DBCONFIG_ENABLE_COMMENTS 1022 /* int int* */ |
| 147 |
#define SQLITE_DBCONFIG_FP_DIGITS 1023 /* int int* */ |
| 148 |
#define SQLITE_DBCONFIG_MAX 1023 /* Largest DBCONFIG */ |
| 149 |
</pre></blockquote> |
| 150 |
<p> |
| 151 |
These constants are the available integer configuration options that |
| 152 |
can be passed as the second parameter to the <a href="../c3ref/db_config.html">sqlite3_db_config()</a> interface.</p> |
| 153 |
|
| 154 |
<p>The <a href="../c3ref/db_config.html">sqlite3_db_config()</a> interface is a var-args function. It takes a |
| 155 |
variable number of parameters, though always at least two. The number of |
| 156 |
parameters passed into sqlite3_db_config() depends on which of these |
| 157 |
constants is given as the second parameter. This documentation page |
| 158 |
refers to parameters beyond the second as "arguments". Thus, when this |
| 159 |
page says "the N-th argument" it means "the N-th parameter past the |
| 160 |
configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".</p> |
| 161 |
|
| 162 |
<p>New configuration options may be added in future releases of SQLite. |
| 163 |
Existing configuration options might be discontinued. Applications |
| 164 |
should check the return code from <a href="../c3ref/db_config.html">sqlite3_db_config()</a> to make sure that |
| 165 |
the call worked. The <a href="../c3ref/db_config.html">sqlite3_db_config()</a> interface will return a |
| 166 |
non-zero <a href="../rescode.html">error code</a> if a discontinued or unsupported configuration option |
| 167 |
is invoked.</p> |
| 168 |
|
| 169 |
<p><dl> |
| 170 |
<a name="sqlitedbconfiglookaside"></a> |
| 171 |
|
| 172 |
<dt>SQLITE_DBCONFIG_LOOKASIDE</dt> |
| 173 |
<dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the |
| 174 |
configuration of the <a href="../malloc.html#lookaside">lookaside memory allocator</a> within a database |
| 175 |
connection. |
| 176 |
The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i> |
| 177 |
in the <a href="../c3ref/c_dbconfig_defensive.html#dbconfigarguments">usual format</a>. |
| 178 |
The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two, |
| 179 |
so that a call to <a href="../c3ref/db_config.html">sqlite3_db_config()</a> that uses SQLITE_DBCONFIG_LOOKASIDE |
| 180 |
should have a total of five parameters. |
| 181 |
<ol> |
| 182 |
<li><p>The first argument ("buf") is a |
| 183 |
pointer to a memory buffer to use for lookaside memory. |
| 184 |
The first argument may be NULL in which case SQLite will allocate the |
| 185 |
lookaside buffer itself using <a href="../c3ref/free.html">sqlite3_malloc()</a>. |
| 186 |
<li><P>The second argument ("sz") is the |
| 187 |
size of each lookaside buffer slot. Lookaside is disabled if "sz" |
| 188 |
is less than 8. The "sz" argument should be a multiple of 8 less than |
| 189 |
65536. If "sz" does not meet this constraint, it is reduced in size until |
| 190 |
it does. |
| 191 |
<li><p>The third argument ("cnt") is the number of slots. |
| 192 |
Lookaside is disabled if "cnt"is less than 1. |
| 193 |
that the product of "sz" and "cnt" does not exceed 2,147,418,112. The "cnt" |
| 194 |
parameter is usually chosen so that the product of "sz" and "cnt" is less |
| 195 |
than 1,000,000. |
| 196 |
</ol> |
| 197 |
<p>If the "buf" argument is not NULL, then it must |
| 198 |
point to a memory buffer with a size that is greater than |
| 199 |
or equal to the product of "sz" and "cnt". |
| 200 |
The buffer must be aligned to an 8-byte boundary. |
| 201 |
The lookaside memory |
| 202 |
configuration for a database connection can only be changed when that |
| 203 |
connection is not currently using lookaside memory, or in other words |
| 204 |
when the value returned by <a href="../c3ref/c_dbstatus_options.html#sqlitedbstatuslookasideused">SQLITE_DBSTATUS_LOOKASIDE_USED</a> is zero. |
| 205 |
Any attempt to change the lookaside memory configuration when lookaside |
| 206 |
memory is in use leaves the configuration unchanged and returns |
| 207 |
<a href="../rescode.html#busy">SQLITE_BUSY</a>. |
| 208 |
If the "buf" argument is NULL and an attempt |
| 209 |
to allocate memory based on "sz" and "cnt" fails, then |
| 210 |
lookaside is silently disabled. |
| 211 |
<p> |
| 212 |
The <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a> configuration option can be used to set the |
| 213 |
default lookaside configuration at initialization. The |
| 214 |
<a href="../compile.html#default_lookaside">-DSQLITE_DEFAULT_LOOKASIDE</a> option can be used to set the default lookaside |
| 215 |
configuration at compile-time. Typical values for lookaside are 1200 for |
| 216 |
"sz" and 40 to 100 for "cnt". |
| 217 |
</dd></p> |
| 218 |
|
| 219 |
<p><a name="sqlitedbconfigenablefkey"></a> |
| 220 |
|
| 221 |
<dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> |
| 222 |
<dd> This option is used to enable or disable the enforcement of |
| 223 |
<a href="../foreignkeys.html">foreign key constraints</a>. This is the same setting that is |
| 224 |
enabled or disabled by the <a href="../pragma.html#pragma_foreign_keys">PRAGMA foreign_keys</a> statement. |
| 225 |
The first argument is an integer which is 0 to disable FK enforcement, |
| 226 |
positive to enable FK enforcement or negative to leave FK enforcement |
| 227 |
unchanged. The second parameter is a pointer to an integer into which |
| 228 |
is written 0 or 1 to indicate whether FK enforcement is off or on |
| 229 |
following this call. The second parameter may be a NULL pointer, in |
| 230 |
which case the FK enforcement setting is not reported back. </dd></p> |
| 231 |
|
| 232 |
<p><a name="sqlitedbconfigenabletrigger"></a> |
| 233 |
|
| 234 |
<dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> |
| 235 |
<dd> This option is used to enable or disable <a href="../lang_createtrigger.html">triggers</a>. |
| 236 |
There should be two additional arguments. |
| 237 |
The first argument is an integer which is 0 to disable triggers, |
| 238 |
positive to enable triggers or negative to leave the setting unchanged. |
| 239 |
The second parameter is a pointer to an integer into which |
| 240 |
is written 0 or 1 to indicate whether triggers are disabled or enabled |
| 241 |
following this call. The second parameter may be a NULL pointer, in |
| 242 |
which case the trigger setting is not reported back.</p> |
| 243 |
|
| 244 |
<p><p>Originally this option disabled all triggers. However, since |
| 245 |
SQLite version 3.35.0, TEMP triggers are still allowed even if |
| 246 |
this option is off. So, in other words, this option now only disables |
| 247 |
triggers in the main database schema or in the schemas of <a href="../lang_attach.html">ATTACH</a>-ed |
| 248 |
databases. </dd></p> |
| 249 |
|
| 250 |
<p><a name="sqlitedbconfigenableview"></a> |
| 251 |
|
| 252 |
<dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt> |
| 253 |
<dd> This option is used to enable or disable <a href="../lang_createview.html">views</a>. |
| 254 |
There must be two additional arguments. |
| 255 |
The first argument is an integer which is 0 to disable views, |
| 256 |
positive to enable views or negative to leave the setting unchanged. |
| 257 |
The second parameter is a pointer to an integer into which |
| 258 |
is written 0 or 1 to indicate whether views are disabled or enabled |
| 259 |
following this call. The second parameter may be a NULL pointer, in |
| 260 |
which case the view setting is not reported back.</p> |
| 261 |
|
| 262 |
<p><p>Originally this option disabled all views. However, since |
| 263 |
SQLite version 3.35.0, TEMP views are still allowed even if |
| 264 |
this option is off. So, in other words, this option now only disables |
| 265 |
views in the main database schema or in the schemas of ATTACH-ed |
| 266 |
databases. </dd></p> |
| 267 |
|
| 268 |
<p><a name="sqlitedbconfigenablefts3tokenizer"></a> |
| 269 |
|
| 270 |
<dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> |
| 271 |
<dd> This option is used to enable or disable using the |
| 272 |
<a href="../fts3.html#f3tknzr">fts3_tokenizer()</a> function - part of the <a href="../fts3.html">FTS3</a> full-text search engine |
| 273 |
extension - without using bound parameters as the parameters. Doing so |
| 274 |
is disabled by default. There must be two additional arguments. The first |
| 275 |
argument is an integer. If it is passed 0, then using fts3_tokenizer() |
| 276 |
without bound parameters is disabled. If it is passed a positive value, |
| 277 |
then calling fts3_tokenizer without bound parameters is enabled. If it |
| 278 |
is passed a negative value, this setting is not modified - this can be |
| 279 |
used to query for the current setting. The second parameter is a pointer |
| 280 |
to an integer into which is written 0 or 1 to indicate the current value |
| 281 |
of this setting (after it is modified, if applicable). The second |
| 282 |
parameter may be a NULL pointer, in which case the value of the setting |
| 283 |
is not reported back. Refer to <a href="../fts3.html">FTS3</a> documentation for further details. |
| 284 |
</dd></p> |
| 285 |
|
| 286 |
<p><a name="sqlitedbconfigenableloadextension"></a> |
| 287 |
|
| 288 |
<dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> |
| 289 |
<dd> This option is used to enable or disable the <a href="../c3ref/load_extension.html">sqlite3_load_extension()</a> |
| 290 |
interface independently of the <a href="../lang_corefunc.html#load_extension">load_extension()</a> SQL function. |
| 291 |
The <a href="../c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> API enables or disables both the |
| 292 |
C-API <a href="../c3ref/load_extension.html">sqlite3_load_extension()</a> and the SQL function <a href="../lang_corefunc.html#load_extension">load_extension()</a>. |
| 293 |
There must be two additional arguments. |
| 294 |
When the first argument to this interface is 1, then only the C-API is |
| 295 |
enabled and the SQL function remains disabled. If the first argument to |
| 296 |
this interface is 0, then both the C-API and the SQL function are disabled. |
| 297 |
If the first argument is -1, then no changes are made to the state of either |
| 298 |
the C-API or the SQL function. |
| 299 |
The second parameter is a pointer to an integer into which |
| 300 |
is written 0 or 1 to indicate whether <a href="../c3ref/load_extension.html">sqlite3_load_extension()</a> interface |
| 301 |
is disabled or enabled following this call. The second parameter may |
| 302 |
be a NULL pointer, in which case the new setting is not reported back. |
| 303 |
</dd></p> |
| 304 |
|
| 305 |
<p><a name="sqlitedbconfigmaindbname"></a> |
| 306 |
<dt>SQLITE_DBCONFIG_MAINDBNAME</dt> |
| 307 |
<dd> This option is used to change the name of the "main" database |
| 308 |
schema. This option does not follow the |
| 309 |
<a href="../c3ref/c_dbconfig_defensive.html#dbconfigarguments">usual SQLITE_DBCONFIG argument format</a>. |
| 310 |
This option takes exactly one additional argument so that the |
| 311 |
<a href="../c3ref/db_config.html">sqlite3_db_config()</a> call has a total of three parameters. The |
| 312 |
extra argument must be a pointer to a constant UTF8 string which |
| 313 |
will become the new schema name in place of "main". SQLite does |
| 314 |
not make a copy of the new main schema name string, so the application |
| 315 |
must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME |
| 316 |
is unchanged until after the database connection closes. |
| 317 |
</dd></p> |
| 318 |
|
| 319 |
<p><a name="sqlitedbconfignockptonclose"></a> |
| 320 |
|
| 321 |
<dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> |
| 322 |
<dd> Usually, when a database in <a href="../wal.html">WAL mode</a> is closed or detached from a |
| 323 |
database handle, SQLite checks if if there are other connections to the |
| 324 |
same database, and if there are no other database connection (if the |
| 325 |
connection being closed is the last open connection to the database), |
| 326 |
then SQLite performs a <a href="../wal.html#ckpt">checkpoint</a> before closing the connection and |
| 327 |
deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can |
| 328 |
be used to override that behavior. The first argument passed to this |
| 329 |
operation (the third parameter to <a href="../c3ref/db_config.html">sqlite3_db_config()</a>) is an integer |
| 330 |
which is positive to disable checkpoints-on-close, or zero (the default) |
| 331 |
to enable them, and negative to leave the setting unchanged. |
| 332 |
The second argument (the fourth parameter) is a pointer to an integer |
| 333 |
into which is written 0 or 1 to indicate whether checkpoints-on-close |
| 334 |
have been disabled - 0 if they are not disabled, 1 if they are. |
| 335 |
</dd></p> |
| 336 |
|
| 337 |
<p><a name="sqlitedbconfigenableqpsg"></a> |
| 338 |
<dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> |
| 339 |
<dd>The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates |
| 340 |
the <a href="../queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG). When the QPSG is active, |
| 341 |
a single SQL query statement will always use the same algorithm regardless |
| 342 |
of values of <a href="../lang_expr.html#varparam">bound parameters</a>. The QPSG disables some query optimizations |
| 343 |
that look at the values of bound parameters, which can make some queries |
| 344 |
slower. But the QPSG has the advantage of more predictable behavior. With |
| 345 |
the QPSG active, SQLite will always use the same query plan in the field as |
| 346 |
was used during testing in the lab. |
| 347 |
The first argument to this setting is an integer which is 0 to disable |
| 348 |
the QPSG, positive to enable QPSG, or negative to leave the setting |
| 349 |
unchanged. The second parameter is a pointer to an integer into which |
| 350 |
is written 0 or 1 to indicate whether the QPSG is disabled or enabled |
| 351 |
following this call. |
| 352 |
</dd></p> |
| 353 |
|
| 354 |
<p><a name="sqlitedbconfigtriggereqp"></a> |
| 355 |
<dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt> |
| 356 |
<dd> By default, the output of EXPLAIN QUERY PLAN commands does not |
| 357 |
include output for any operations performed by trigger programs. This |
| 358 |
option is used to set or clear (the default) a flag that governs this |
| 359 |
behavior. The first parameter passed to this operation is an integer - |
| 360 |
positive to enable output for trigger programs, or zero to disable it, |
| 361 |
or negative to leave the setting unchanged. |
| 362 |
The second parameter is a pointer to an integer into which is written |
| 363 |
0 or 1 to indicate whether output-for-triggers has been disabled - 0 if |
| 364 |
it is not disabled, 1 if it is. |
| 365 |
</dd></p> |
| 366 |
|
| 367 |
<p><a name="sqlitedbconfigresetdatabase"></a> |
| 368 |
<dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> |
| 369 |
<dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run |
| 370 |
<a href="../lang_vacuum.html">VACUUM</a> in order to reset a database back to an empty database |
| 371 |
with no schema and no content. The following process works even for |
| 372 |
a badly corrupted database file: |
| 373 |
<ol> |
| 374 |
<li> If the database connection is newly opened, make sure it has read the |
| 375 |
database schema by preparing then discarding some query against the |
| 376 |
database, or calling sqlite3_table_column_metadata(), ignoring any |
| 377 |
errors. This step is only necessary if the application desires to keep |
| 378 |
the database in WAL mode after the reset if it was in WAL mode before |
| 379 |
the reset. |
| 380 |
<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); |
| 381 |
<li> <a href="../c3ref/exec.html">sqlite3_exec</a>(db, "<a href="../lang_vacuum.html">VACUUM</a>", 0, 0, 0); |
| 382 |
<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); |
| 383 |
</ol> |
| 384 |
Because resetting a database is destructive and irreversible, the |
| 385 |
process requires the use of this obscure API and multiple steps to |
| 386 |
help ensure that it does not happen by accident. Because this |
| 387 |
feature must be capable of resetting corrupt databases, and |
| 388 |
shutting down virtual tables may require access to that corrupt |
| 389 |
storage, the library must abandon any installed virtual tables |
| 390 |
without calling their xDestroy() methods.</p> |
| 391 |
|
| 392 |
<p><a name="sqlitedbconfigdefensive"></a> |
| 393 |
<dt>SQLITE_DBCONFIG_DEFENSIVE</dt> |
| 394 |
<dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the |
| 395 |
"defensive" flag for a database connection. When the defensive |
| 396 |
flag is enabled, language features that allow ordinary SQL to |
| 397 |
deliberately corrupt the database file are disabled. The disabled |
| 398 |
features include but are not limited to the following: |
| 399 |
<ul> |
| 400 |
<li> The <a href="../pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> statement. |
| 401 |
<li> The <a href="../pragma.html#pragma_journal_mode">PRAGMA journal_mode=OFF</a> statement. |
| 402 |
<li> The <a href="../pragma.html#pragma_schema_version">PRAGMA schema_version=N</a> statement. |
| 403 |
<li> Writes to the <a href="../dbpage.html">sqlite_dbpage</a> virtual table. |
| 404 |
<li> Direct writes to <a href="../vtab.html#xshadowname">shadow tables</a>. |
| 405 |
</ul> |
| 406 |
</dd></p> |
| 407 |
|
| 408 |
<p><a name="sqlitedbconfigwritableschema"></a> |
| 409 |
<dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt> |
| 410 |
<dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the |
| 411 |
"writable_schema" flag. This has the same effect and is logically equivalent |
| 412 |
to setting <a href="../pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> or <a href="../pragma.html#pragma_writable_schema">PRAGMA writable_schema=OFF</a>. |
| 413 |
The first argument to this setting is an integer which is 0 to disable |
| 414 |
the writable_schema, positive to enable writable_schema, or negative to |
| 415 |
leave the setting unchanged. The second parameter is a pointer to an |
| 416 |
integer into which is written 0 or 1 to indicate whether the writable_schema |
| 417 |
is enabled or disabled following this call. |
| 418 |
</dd></p> |
| 419 |
|
| 420 |
<p><a name="sqlitedbconfiglegacyaltertable"></a> |
| 421 |
|
| 422 |
<dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt> |
| 423 |
<dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates |
| 424 |
the legacy behavior of the <a href="../lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command such that it |
| 425 |
behaves as it did prior to <a href="../releaselog/3_24_0.html">version 3.24.0</a> (2018-06-04). See the |
| 426 |
"Compatibility Notice" on the <a href="../lang_altertable.html#altertabrename">ALTER TABLE RENAME documentation</a> for |
| 427 |
additional information. This feature can also be turned on and off |
| 428 |
using the <a href="../pragma.html#pragma_legacy_alter_table">PRAGMA legacy_alter_table</a> statement. |
| 429 |
</dd></p> |
| 430 |
|
| 431 |
<p><a name="sqlitedbconfigdqsdml"></a> |
| 432 |
|
| 433 |
<dt>SQLITE_DBCONFIG_DQS_DML</dt> |
| 434 |
<dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates |
| 435 |
the legacy <a href="../quirks.html#dblquote">double-quoted string literal</a> misfeature for DML statements |
| 436 |
only, that is DELETE, INSERT, SELECT, and UPDATE statements. The |
| 437 |
default value of this setting is determined by the <a href="../compile.html#dqs">-DSQLITE_DQS</a> |
| 438 |
compile-time option. |
| 439 |
</dd></p> |
| 440 |
|
| 441 |
<p><a name="sqlitedbconfigdqsddl"></a> |
| 442 |
|
| 443 |
<dt>SQLITE_DBCONFIG_DQS_DDL</dt> |
| 444 |
<dd>The SQLITE_DBCONFIG_DQS option activates or deactivates |
| 445 |
the legacy <a href="../quirks.html#dblquote">double-quoted string literal</a> misfeature for DDL statements, |
| 446 |
such as CREATE TABLE and CREATE INDEX. The |
| 447 |
default value of this setting is determined by the <a href="../compile.html#dqs">-DSQLITE_DQS</a> |
| 448 |
compile-time option. |
| 449 |
</dd></p> |
| 450 |
|
| 451 |
<p><a name="sqlitedbconfigtrustedschema"></a> |
| 452 |
|
| 453 |
<dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt> |
| 454 |
<dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to |
| 455 |
assume that database schemas are untainted by malicious content. |
| 456 |
When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite |
| 457 |
takes additional defensive steps to protect the application from harm |
| 458 |
including: |
| 459 |
<ul> |
| 460 |
<li> Prohibit the use of SQL functions inside triggers, views, |
| 461 |
CHECK constraints, DEFAULT clauses, expression indexes, |
| 462 |
partial indexes, or generated columns |
| 463 |
unless those functions are tagged with <a href="../c3ref/c_deterministic.html#sqliteinnocuous">SQLITE_INNOCUOUS</a>. |
| 464 |
<li> Prohibit the use of virtual tables inside of triggers or views |
| 465 |
unless those virtual tables are tagged with <a href="../c3ref/c_vtab_constraint_support.html#sqlitevtabinnocuous">SQLITE_VTAB_INNOCUOUS</a>. |
| 466 |
</ul> |
| 467 |
This setting defaults to "on" for legacy compatibility, however |
| 468 |
all applications are advised to turn it off if possible. This setting |
| 469 |
can also be controlled using the <a href="../pragma.html#pragma_trusted_schema">PRAGMA trusted_schema</a> statement. |
| 470 |
</dd></p> |
| 471 |
|
| 472 |
<p><a name="sqlitedbconfiglegacyfileformat"></a> |
| 473 |
|
| 474 |
<dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt> |
| 475 |
<dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates |
| 476 |
the legacy file format flag. When activated, this flag causes all newly |
| 477 |
created database files to have a schema format version number (the 4-byte |
| 478 |
integer found at offset 44 into the database header) of 1. This in turn |
| 479 |
means that the resulting database file will be readable and writable by |
| 480 |
any SQLite version back to 3.0.0 (2004-06-18). Without this setting, |
| 481 |
newly created databases are generally not understandable by SQLite versions |
| 482 |
prior to 3.3.0 (2006-01-11). As these words are written, there |
| 483 |
is now scarcely any need to generate database files that are compatible |
| 484 |
all the way back to version 3.0.0, and so this setting is of little |
| 485 |
practical use, but is provided so that SQLite can continue to claim the |
| 486 |
ability to generate new database files that are compatible with version |
| 487 |
3.0.0. |
| 488 |
<p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on, |
| 489 |
the <a href="../lang_vacuum.html">VACUUM</a> command will fail with an obscure error when attempting to |
| 490 |
process a table with generated columns and a descending index. This is |
| 491 |
not considered a bug since SQLite versions 3.3.0 and earlier do not support |
| 492 |
either generated columns or descending indexes. |
| 493 |
</dd></p> |
| 494 |
|
| 495 |
<p><a name="sqlitedbconfigstmtscanstatus"></a> |
| 496 |
|
| 497 |
<dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt> |
| 498 |
<dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in |
| 499 |
<a href="../compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a> builds. In this case, it sets or clears |
| 500 |
a flag that enables collection of run-time performance statistics |
| 501 |
used by <a href="../c3ref/stmt_scanstatus.html">sqlite3_stmt_scanstatus_v2()</a> and the <a href="../bytecodevtab.html#nexec">nexec and ncycle</a> |
| 502 |
columns of the <a href="../bytecodevtab.html">bytecode virtual table</a>. |
| 503 |
For statistics to be collected, the flag must be set on |
| 504 |
the database handle both when the SQL statement is |
| 505 |
<a href="../c3ref/prepare.html">prepared</a> and when it is <a href="../c3ref/step.html">stepped</a>. |
| 506 |
The flag is set (collection of statistics is enabled) by default. |
| 507 |
<p>This option takes two arguments: an integer and a pointer to |
| 508 |
an integer. The first argument is 1, 0, or -1 to enable, disable, or |
| 509 |
leave unchanged the statement scanstatus option. If the second argument |
| 510 |
is not NULL, then the value of the statement scanstatus setting after |
| 511 |
processing the first argument is written into the integer that the second |
| 512 |
argument points to. |
| 513 |
</dd></p> |
| 514 |
|
| 515 |
<p><a name="sqlitedbconfigreversescanorder"></a> |
| 516 |
|
| 517 |
<dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt> |
| 518 |
<dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order |
| 519 |
in which tables and indexes are scanned so that the scans start at the end |
| 520 |
and work toward the beginning rather than starting at the beginning and |
| 521 |
working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the |
| 522 |
same as setting <a href="../pragma.html#pragma_reverse_unordered_selects">PRAGMA reverse_unordered_selects</a>. <p>This option takes |
| 523 |
two arguments which are an integer and a pointer to an integer. The first |
| 524 |
argument is 1, 0, or -1 to enable, disable, or leave unchanged the |
| 525 |
reverse scan order flag, respectively. If the second argument is not NULL, |
| 526 |
then 0 or 1 is written into the integer that the second argument points to |
| 527 |
depending on if the reverse scan order flag is set after processing the |
| 528 |
first argument. |
| 529 |
</dd></p> |
| 530 |
|
| 531 |
<p><a name="sqlitedbconfigenableattachcreate"></a> |
| 532 |
|
| 533 |
<dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt> |
| 534 |
<dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables |
| 535 |
the ability of the <a href="../lang_attach.html">ATTACH DATABASE</a> SQL command to create a new database |
| 536 |
file if the database filed named in the ATTACH command does not already |
| 537 |
exist. This ability of ATTACH to create a new database is enabled by |
| 538 |
default. Applications can disable or reenable the ability for ATTACH to |
| 539 |
create new database files using this DBCONFIG option.<p> |
| 540 |
This option takes two arguments which are an integer and a pointer |
| 541 |
to an integer. The first argument is 1, 0, or -1 to enable, disable, or |
| 542 |
leave unchanged the attach-create flag, respectively. If the second |
| 543 |
argument is not NULL, then 0 or 1 is written into the integer that the |
| 544 |
second argument points to depending on if the attach-create flag is set |
| 545 |
after processing the first argument. |
| 546 |
</dd></p> |
| 547 |
|
| 548 |
<p><a name="sqlitedbconfigenableattachwrite"></a> |
| 549 |
|
| 550 |
<dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt> |
| 551 |
<dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the |
| 552 |
ability of the <a href="../lang_attach.html">ATTACH DATABASE</a> SQL command to open a database for writing. |
| 553 |
This capability is enabled by default. Applications can disable or |
| 554 |
reenable this capability using the current DBCONFIG option. If |
| 555 |
this capability is disabled, the <a href="../lang_attach.html">ATTACH</a> command will still work, |
| 556 |
but the database will be opened read-only. If this option is disabled, |
| 557 |
then the ability to create a new database using <a href="../lang_attach.html">ATTACH</a> is also disabled, |
| 558 |
regardless of the value of the <a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableattachcreate">SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</a> |
| 559 |
option.<p> |
| 560 |
This option takes two arguments which are an integer and a pointer |
| 561 |
to an integer. The first argument is 1, 0, or -1 to enable, disable, or |
| 562 |
leave unchanged the ability to ATTACH another database for writing, |
| 563 |
respectively. If the second argument is not NULL, then 0 or 1 is written |
| 564 |
into the integer to which the second argument points, depending on whether |
| 565 |
the ability to ATTACH a read/write database is enabled or disabled |
| 566 |
after processing the first argument. |
| 567 |
</dd></p> |
| 568 |
|
| 569 |
<p><a name="sqlitedbconfigenablecomments"></a> |
| 570 |
|
| 571 |
<dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt> |
| 572 |
<dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the |
| 573 |
ability to include comments in SQL text. Comments are enabled by default. |
| 574 |
An application can disable or reenable comments in SQL text using this |
| 575 |
DBCONFIG option.<p> |
| 576 |
This option takes two arguments which are an integer and a pointer |
| 577 |
to an integer. The first argument is 1, 0, or -1 to enable, disable, or |
| 578 |
leave unchanged the ability to use comments in SQL text, |
| 579 |
respectively. If the second argument is not NULL, then 0 or 1 is written |
| 580 |
into the integer that the second argument points to depending on if |
| 581 |
comments are allowed in SQL text after processing the first argument. |
| 582 |
</dd></p> |
| 583 |
|
| 584 |
<p><a name="sqlitedbconfigfpdigits"></a> |
| 585 |
|
| 586 |
<dt>SQLITE_DBCONFIG_FP_DIGITS</dt> |
| 587 |
<dd>The SQLITE_DBCONFIG_FP_DIGITS setting is a small integer that determines |
| 588 |
the number of significant digits that SQLite will attempt to preserve when |
| 589 |
converting floating point numbers (IEEE 754 "doubles") into text. The |
| 590 |
default value 17, as of SQLite version 3.52.0. The value was 15 in all |
| 591 |
prior versions.<p> |
| 592 |
This option takes two arguments which are an integer and a pointer |
| 593 |
to an integer. The first argument is a small integer, between 3 and 23, or |
| 594 |
zero. The FP_DIGITS setting is changed to that small integer, or left |
| 595 |
unaltered if the first argument is zero or out of range. The second argument |
| 596 |
is a pointer to an integer. If the pointer is not NULL, then the value of |
| 597 |
the FP_DIGITS setting, after possibly being modified by the first |
| 598 |
arguments, is written into the integer to which the second argument points. |
| 599 |
</dd></p> |
| 600 |
|
| 601 |
<p></dl></p> |
| 602 |
|
| 603 |
<p><a name="dbconfigarguments"></a> |
| 604 |
<h3>Arguments To SQLITE_DBCONFIG Options</h3></p> |
| 605 |
|
| 606 |
<p><p>Most of the SQLITE_DBCONFIG options take two arguments, so that the |
| 607 |
overall call to <a href="../c3ref/db_config.html">sqlite3_db_config()</a> has a total of four parameters. |
| 608 |
The first argument (the third parameter to sqlite3_db_config()) is |
| 609 |
an integer. |
| 610 |
The second argument is a pointer to an integer. If the first argument is 1, |
| 611 |
then the option becomes enabled. If the first integer argument is 0, |
| 612 |
then the option is disabled. |
| 613 |
If the first argument is -1, then the option setting |
| 614 |
is unchanged. The second argument, the pointer to an integer, may be NULL. |
| 615 |
If the second argument is not NULL, then a value of 0 or 1 is written into |
| 616 |
the integer to which the second argument points, depending on whether the |
| 617 |
setting is disabled or enabled after applying any changes specified by |
| 618 |
the first argument.</p> |
| 619 |
|
| 620 |
<p><p>While most SQLITE_DBCONFIG options use the argument format |
| 621 |
described in the previous paragraph, the <a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfigmaindbname">SQLITE_DBCONFIG_MAINDBNAME</a>, |
| 622 |
<a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a>, and <a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfigfpdigits">SQLITE_DBCONFIG_FP_DIGITS</a> options |
| 623 |
are different. See the documentation of those exceptional options for |
| 624 |
details. |
| 625 |
</p><p>See also lists of |
| 626 |
<a href="../c3ref/objlist.html">Objects</a>, |
| 627 |
<a href="../c3ref/constlist.html">Constants</a>, and |
| 628 |
<a href="../c3ref/funclist.html">Functions</a>.</p> |
| 629 |
|