diff options
Diffstat (limited to 'www/c3ref/c_dbconfig_defensive.html')
| -rw-r--r-- | www/c3ref/c_dbconfig_defensive.html | 445 |
1 files changed, 445 insertions, 0 deletions
diff --git a/www/c3ref/c_dbconfig_defensive.html b/www/c3ref/c_dbconfig_defensive.html new file mode 100644 index 0000000..3a3506e --- /dev/null +++ b/www/c3ref/c_dbconfig_defensive.html @@ -0,0 +1,445 @@ +<!DOCTYPE html> +<html><head> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +<link href="../sqlite.css" rel="stylesheet"> +<title>Database Connection Configuration Options</title> +<!-- path=../ --> +</head> +<body> +<div class=nosearch> +<a href="../index.html"> +<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0"> +</a> +<div><!-- IE hack to prevent disappearing logo --></div> +<div class="tagline desktoponly"> +Small. Fast. Reliable.<br>Choose any three. +</div> +<div class="menu mainmenu"> +<ul> +<li><a href="../index.html">Home</a> +<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> +<li class='wideonly'><a href='../about.html'>About</a> +<li class='desktoponly'><a href="../docs.html">Documentation</a> +<li class='desktoponly'><a href="../download.html">Download</a> +<li class='wideonly'><a href='../copyright.html'>License</a> +<li class='desktoponly'><a href="../support.html">Support</a> +<li class='desktoponly'><a href="../prosupport.html">Purchase</a> +<li class='search' id='search_menubutton'> +<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> +</ul> +</div> +<div class="menu submenu" id="submenu"> +<ul> +<li><a href='../about.html'>About</a> +<li><a href='../docs.html'>Documentation</a> +<li><a href='../download.html'>Download</a> +<li><a href='../support.html'>Support</a> +<li><a href='../prosupport.html'>Purchase</a> +</ul> +</div> +<div class="searchmenu" id="searchmenu"> +<form method="GET" action="../search"> +<select name="s" id="searchtype"> +<option value="d">Search Documentation</option> +<option value="c">Search Changelog</option> +</select> +<input type="text" name="q" id="searchbox" value=""> +<input type="submit" value="Go"> +</form> +</div> +</div> +<script> +function toggle_div(nm) { +var w = document.getElementById(nm); +if( w.style.display=="block" ){ +w.style.display = "none"; +}else{ +w.style.display = "block"; +} +} +function toggle_search() { +var w = document.getElementById("searchmenu"); +if( w.style.display=="block" ){ +w.style.display = "none"; +} else { +w.style.display = "block"; +setTimeout(function(){ +document.getElementById("searchbox").focus() +}, 30); +} +} +function div_off(nm){document.getElementById(nm).style.display="none";} +window.onbeforeunload = function(e){div_off("submenu");} +/* Disable the Search feature if we are not operating from CGI, since */ +/* Search is accomplished using CGI and will not work without it. */ +if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ +document.getElementById("search_menubutton").style.display = "none"; +} +/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ +function hideorshow(btn,obj){ +var x = document.getElementById(obj); +var b = document.getElementById(btn); +if( x.style.display!='none' ){ +x.style.display = 'none'; +b.innerHTML='show'; +}else{ +x.style.display = ''; +b.innerHTML='hide'; +} +return false; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> +<!-- keywords: SQLITE_DBCONFIG_DEFENSIVE SQLITE_DBCONFIG_DQS_DDL SQLITE_DBCONFIG_DQS_DML 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_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_TRIGGER_EQP SQLITE_DBCONFIG_TRUSTED_SCHEMA SQLITE_DBCONFIG_WRITABLE_SCHEMA --> +<div class=nosearch> +<a href="intro.html"><h2>SQLite C Interface</h2></a> +<h2>Database Connection Configuration Options</h2> +</div> +<blockquote><pre> +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ +#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ +#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ +#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ +#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */ +#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */ +#define SQLITE_DBCONFIG_MAX 1017 /* Largest DBCONFIG */ +</pre></blockquote> +<p> +These constants are the available integer configuration options that +can be passed as the second argument to the <a href="../c3ref/db_config.html">sqlite3_db_config()</a> interface.</p> + +<p>New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. Applications +should check the return code from <a href="../c3ref/db_config.html">sqlite3_db_config()</a> to make sure that +the call worked. The <a href="../c3ref/db_config.html">sqlite3_db_config()</a> interface will return a +non-zero <a href="../rescode.html">error code</a> if a discontinued or unsupported configuration option +is invoked.</p> + +<p><dl> +<a name="sqlitedbconfiglookaside"></a> + +<dt>SQLITE_DBCONFIG_LOOKASIDE</dt> +<dd> This option takes three additional arguments that determine the +<a href="../malloc.html#lookaside">lookaside memory allocator</a> configuration for the <a href="../c3ref/sqlite3.html">database connection</a>. +The first argument (the third parameter to <a href="../c3ref/db_config.html">sqlite3_db_config()</a> is a +pointer to a memory buffer to use for lookaside memory. +The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb +may be NULL in which case SQLite will allocate the +lookaside buffer itself using <a href="../c3ref/free.html">sqlite3_malloc()</a>. The second argument is the +size of each lookaside buffer slot. The third argument is the number of +slots. The size of the buffer in the first argument must be greater than +or equal to the product of the second and third arguments. The buffer +must be aligned to an 8-byte boundary. If the second argument to +SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally +rounded down to the next smaller multiple of 8. The lookaside memory +configuration for a database connection can only be changed when that +connection is not currently using lookaside memory, or in other words +when the "current value" returned by +<a href="../c3ref/db_status.html">sqlite3_db_status</a>(D,<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>,...) is zero. +Any attempt to change the lookaside memory configuration when lookaside +memory is in use leaves the configuration unchanged and returns +<a href="../rescode.html#busy">SQLITE_BUSY</a>.</dd></p> + +<p><a name="sqlitedbconfigenablefkey"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> +<dd> This option is used to enable or disable the enforcement of +<a href="../foreignkeys.html">foreign key constraints</a>. There should be two additional arguments. +The first argument is an integer which is 0 to disable FK enforcement, +positive to enable FK enforcement or negative to leave FK enforcement +unchanged. The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether FK enforcement is off or on +following this call. The second parameter may be a NULL pointer, in +which case the FK enforcement setting is not reported back. </dd></p> + +<p><a name="sqlitedbconfigenabletrigger"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> +<dd> This option is used to enable or disable <a href="../lang_createtrigger.html">triggers</a>. +There should be two additional arguments. +The first argument is an integer which is 0 to disable triggers, +positive to enable triggers or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether triggers are disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the trigger setting is not reported back.</p> + +<p><p>Originally this option disabled all triggers. However, since +SQLite version 3.35.0, TEMP triggers are still allowed even if +this option is off. So, in other words, this option now only disables +triggers in the main database schema or in the schemas of ATTACH-ed +databases. </dd></p> + +<p><a name="sqlitedbconfigenableview"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt> +<dd> This option is used to enable or disable <a href="../lang_createview.html">views</a>. +There should be two additional arguments. +The first argument is an integer which is 0 to disable views, +positive to enable views or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether views are disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the view setting is not reported back.</p> + +<p><p>Originally this option disabled all views. However, since +SQLite version 3.35.0, TEMP views are still allowed even if +this option is off. So, in other words, this option now only disables +views in the main database schema or in the schemas of ATTACH-ed +databases. </dd></p> + +<p><a name="sqlitedbconfigenablefts3tokenizer"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> +<dd> This option is used to enable or disable the +<a href="../fts3.html#f3tknzr">fts3_tokenizer()</a> function which is part of the +<a href="../fts3.html">FTS3</a> full-text search engine extension. +There should be two additional arguments. +The first argument is an integer which is 0 to disable fts3_tokenizer() or +positive to enable fts3_tokenizer() or negative to leave the setting +unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the new setting is not reported back. </dd></p> + +<p><a name="sqlitedbconfigenableloadextension"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> +<dd> This option is used to enable or disable the <a href="../c3ref/load_extension.html">sqlite3_load_extension()</a> +interface independently of the <a href="../lang_corefunc.html#load_extension">load_extension()</a> SQL function. +The <a href="../c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> API enables or disables both the +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>. +There should be two additional arguments. +When the first argument to this interface is 1, then only the C-API is +enabled and the SQL function remains disabled. If the first argument to +this interface is 0, then both the C-API and the SQL function are disabled. +If the first argument is -1, then no changes are made to state of either the +C-API or the SQL function. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether <a href="../c3ref/load_extension.html">sqlite3_load_extension()</a> interface +is disabled or enabled following this call. The second parameter may +be a NULL pointer, in which case the new setting is not reported back. +</dd></p> + +<p><a name="sqlitedbconfigmaindbname"></a> + <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> +<dd> This option is used to change the name of the "main" database +schema. The sole argument is a pointer to a constant UTF8 string +which will become the new schema name in place of "main". SQLite +does not make a copy of the new main schema name string, so the application +must ensure that the argument passed into this DBCONFIG option is unchanged +until after the database connection closes. +</dd></p> + +<p><a name="sqlitedbconfignockptonclose"></a> + +<dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> +<dd> Usually, when a database in wal mode is closed or detached from a +database handle, SQLite checks if this will mean that there are now no +connections at all to the database. If so, it performs a checkpoint +operation before closing the connection. This option may be used to +override this behaviour. The first parameter passed to this operation +is an integer - positive to disable checkpoints-on-close, or zero (the +default) to enable them, and negative to leave the setting unchanged. +The second parameter is a pointer to an integer +into which is written 0 or 1 to indicate whether checkpoints-on-close +have been disabled - 0 if they are not disabled, 1 if they are. +</dd></p> + +<p><a name="sqlitedbconfigenableqpsg"></a> + <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> +<dd>The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates +the <a href="../queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG). When the QPSG is active, +a single SQL query statement will always use the same algorithm regardless +of values of <a href="../lang_expr.html#varparam">bound parameters</a>. The QPSG disables some query optimizations +that look at the values of bound parameters, which can make some queries +slower. But the QPSG has the advantage of more predictable behavior. With +the QPSG active, SQLite will always use the same query plan in the field as +was used during testing in the lab. +The first argument to this setting is an integer which is 0 to disable +the QPSG, positive to enable QPSG, or negative to leave the setting +unchanged. The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether the QPSG is disabled or enabled +following this call. +</dd></p> + +<p><a name="sqlitedbconfigtriggereqp"></a> + <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt> +<dd> By default, the output of EXPLAIN QUERY PLAN commands does not +include output for any operations performed by trigger programs. This +option is used to set or clear (the default) a flag that governs this +behavior. The first parameter passed to this operation is an integer - +positive to enable output for trigger programs, or zero to disable it, +or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether output-for-triggers has been disabled - 0 if +it is not disabled, 1 if it is. +</dd></p> + +<p><a name="sqlitedbconfigresetdatabase"></a> + <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> +<dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run +<a href="../lang_vacuum.html">VACUUM</a> in order to reset a database back to an empty database +with no schema and no content. The following process works even for +a badly corrupted database file: +<ol> +<li> If the database connection is newly opened, make sure it has read the +database schema by preparing then discarding some query against the +database, or calling sqlite3_table_column_metadata(), ignoring any +errors. This step is only necessary if the application desires to keep +the database in WAL mode after the reset if it was in WAL mode before +the reset. +<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); +<li> <a href="../c3ref/exec.html">sqlite3_exec</a>(db, "<a href="../lang_vacuum.html">VACUUM</a>", 0, 0, 0); +<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); +</ol> +Because resetting a database is destructive and irreversible, the +process requires the use of this obscure API and multiple steps to help +ensure that it does not happen by accident.</p> + +<p><a name="sqlitedbconfigdefensive"></a> + <dt>SQLITE_DBCONFIG_DEFENSIVE</dt> +<dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the +"defensive" flag for a database connection. When the defensive +flag is enabled, language features that allow ordinary SQL to +deliberately corrupt the database file are disabled. The disabled +features include but are not limited to the following: +<ul> +<li> The <a href="../pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> statement. +<li> The <a href="../pragma.html#pragma_journal_mode">PRAGMA journal_mode=OFF</a> statement. +<li> The <a href="../pragma.html#pragma_schema_version">PRAGMA schema_version=N</a> statement. +<li> Writes to the <a href="../dbpage.html">sqlite_dbpage</a> virtual table. +<li> Direct writes to <a href="../vtab.html#xshadowname">shadow tables</a>. +</ul> +</dd></p> + +<p><a name="sqlitedbconfigwritableschema"></a> + <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt> +<dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the +"writable_schema" flag. This has the same effect and is logically equivalent +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>. +The first argument to this setting is an integer which is 0 to disable +the writable_schema, positive to enable writable_schema, or negative to +leave the setting unchanged. The second parameter is a pointer to an +integer into which is written 0 or 1 to indicate whether the writable_schema +is enabled or disabled following this call. +</dd></p> + +<p><a name="sqlitedbconfiglegacyaltertable"></a> + +<dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt> +<dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates +the legacy behavior of the <a href="../lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command such it +behaves as it did prior to <a href="../releaselog/3_24_0.html">version 3.24.0</a> (2018-06-04). See the +"Compatibility Notice" on the <a href="../lang_altertable.html#altertabrename">ALTER TABLE RENAME documentation</a> for +additional information. This feature can also be turned on and off +using the <a href="../pragma.html#pragma_legacy_alter_table">PRAGMA legacy_alter_table</a> statement. +</dd></p> + +<p><a name="sqlitedbconfigdqsdml"></a> + +<dt>SQLITE_DBCONFIG_DQS_DML</td> +<dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates +the legacy <a href="../quirks.html#dblquote">double-quoted string literal</a> misfeature for DML statements +only, that is DELETE, INSERT, SELECT, and UPDATE statements. The +default value of this setting is determined by the <a href="../compile.html#dqs">-DSQLITE_DQS</a> +compile-time option. +</dd></p> + +<p><a name="sqlitedbconfigdqsddl"></a> + +<dt>SQLITE_DBCONFIG_DQS_DDL</td> +<dd>The SQLITE_DBCONFIG_DQS option activates or deactivates +the legacy <a href="../quirks.html#dblquote">double-quoted string literal</a> misfeature for DDL statements, +such as CREATE TABLE and CREATE INDEX. The +default value of this setting is determined by the <a href="../compile.html#dqs">-DSQLITE_DQS</a> +compile-time option. +</dd></p> + +<p><a name="sqlitedbconfigtrustedschema"></a> + +<dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</td> +<dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to +assume that database schemas are untainted by malicious content. +When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite +takes additional defensive steps to protect the application from harm +including: +<ul> +<li> Prohibit the use of SQL functions inside triggers, views, +CHECK constraints, DEFAULT clauses, expression indexes, +partial indexes, or generated columns +unless those functions are tagged with <a href="../c3ref/c_deterministic.html#sqliteinnocuous">SQLITE_INNOCUOUS</a>. +<li> Prohibit the use of virtual tables inside of triggers or views +unless those virtual tables are tagged with <a href="../c3ref/c_vtab_constraint_support.html#sqlitevtabinnocuous">SQLITE_VTAB_INNOCUOUS</a>. +</ul> +This setting defaults to "on" for legacy compatibility, however +all applications are advised to turn it off if possible. This setting +can also be controlled using the <a href="../pragma.html#pragma_trusted_schema">PRAGMA trusted_schema</a> statement. +</dd></p> + +<p><a name="sqlitedbconfiglegacyfileformat"></a> + +<dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</td> +<dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates +the legacy file format flag. When activated, this flag causes all newly +created database file to have a schema format version number (the 4-byte +integer found at offset 44 into the database header) of 1. This in turn +means that the resulting database file will be readable and writable by +any SQLite version back to 3.0.0 (2004-06-18). Without this setting, +newly created databases are generally not understandable by SQLite versions +prior to 3.3.0 (2006-01-11). As these words are written, there +is now scarcely any need to generated database files that are compatible +all the way back to version 3.0.0, and so this setting is of little +practical use, but is provided so that SQLite can continue to claim the +ability to generate new database files that are compatible with version +3.0.0. +<p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on, +the <a href="../lang_vacuum.html">VACUUM</a> command will fail with an obscure error when attempting to +process a table with generated columns and a descending index. This is +not considered a bug since SQLite versions 3.3.0 and earlier do not support +either generated columns or decending indexes. +</dd> +</dl> +</p><p>See also lists of + <a href="objlist.html">Objects</a>, + <a href="constlist.html">Constants</a>, and + <a href="funclist.html">Functions</a>.</p> + |