Debian Codegraph @

www/c3ref/c_dbconfig_defensive.html

raw
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