1.Dd December 19, 2018 2.Dt SQLITE_DBCONFIG_MAINDBNAME 3 3.Os 4.Sh NAME 5.Nm SQLITE_DBCONFIG_MAINDBNAME , 6.Nm SQLITE_DBCONFIG_LOOKASIDE , 7.Nm SQLITE_DBCONFIG_ENABLE_FKEY , 8.Nm SQLITE_DBCONFIG_ENABLE_TRIGGER , 9.Nm SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER , 10.Nm SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION , 11.Nm SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE , 12.Nm SQLITE_DBCONFIG_ENABLE_QPSG , 13.Nm SQLITE_DBCONFIG_TRIGGER_EQP , 14.Nm SQLITE_DBCONFIG_RESET_DATABASE , 15.Nm SQLITE_DBCONFIG_DEFENSIVE , 16.Nm SQLITE_DBCONFIG_MAX 17.Nd Database Connection Configuration Options 18.Sh SYNOPSIS 19.Fd #define SQLITE_DBCONFIG_MAINDBNAME 20.Fd #define SQLITE_DBCONFIG_LOOKASIDE 21.Fd #define SQLITE_DBCONFIG_ENABLE_FKEY 22.Fd #define SQLITE_DBCONFIG_ENABLE_TRIGGER 23.Fd #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 24.Fd #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 25.Fd #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 26.Fd #define SQLITE_DBCONFIG_ENABLE_QPSG 27.Fd #define SQLITE_DBCONFIG_TRIGGER_EQP 28.Fd #define SQLITE_DBCONFIG_RESET_DATABASE 29.Fd #define SQLITE_DBCONFIG_DEFENSIVE 30.Fd #define SQLITE_DBCONFIG_MAX 31.Sh DESCRIPTION 32These constants are the available integer configuration options that 33can be passed as the second argument to the sqlite3_db_config() 34interface. 35.Pp 36New configuration options may be added in future releases of SQLite. 37Existing configuration options might be discontinued. 38Applications should check the return code from sqlite3_db_config() 39to make sure that the call worked. 40The sqlite3_db_config() interface will return a 41non-zero error code if a discontinued or unsupported configuration 42option is invoked. 43.Bl -tag -width Ds 44.It SQLITE_DBCONFIG_LOOKASIDE 45This option takes three additional arguments that determine the lookaside memory allocator 46configuration for the database connection. 47The first argument (the third parameter to sqlite3_db_config() 48is a pointer to a memory buffer to use for lookaside memory. 49The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be 50NULL in which case SQLite will allocate the lookaside buffer itself 51using sqlite3_malloc(). 52The second argument is the size of each lookaside buffer slot. 53The third argument is the number of slots. 54The size of the buffer in the first argument must be greater than or 55equal to the product of the second and third arguments. 56The buffer must be aligned to an 8-byte boundary. 57If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple 58of 8, it is internally rounded down to the next smaller multiple of 598. 60The lookaside memory configuration for a database connection can only 61be changed when that connection is not currently using lookaside memory, 62or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_CONFIG_LOOKASIDE,...) 63is zero. 64Any attempt to change the lookaside memory configuration when lookaside 65memory is in use leaves the configuration unchanged and returns SQLITE_BUSY. 66.It SQLITE_DBCONFIG_ENABLE_FKEY 67This option is used to enable or disable the enforcement of foreign key constraints. 68There should be two additional arguments. 69The first argument is an integer which is 0 to disable FK enforcement, 70positive to enable FK enforcement or negative to leave FK enforcement 71unchanged. 72The second parameter is a pointer to an integer into which is written 730 or 1 to indicate whether FK enforcement is off or on following this 74call. 75The second parameter may be a NULL pointer, in which case the FK enforcement 76setting is not reported back. 77.It SQLITE_DBCONFIG_ENABLE_TRIGGER 78This option is used to enable or disable triggers. 79There should be two additional arguments. 80The first argument is an integer which is 0 to disable triggers, positive 81to enable triggers or negative to leave the setting unchanged. 82The second parameter is a pointer to an integer into which is written 830 or 1 to indicate whether triggers are disabled or enabled following 84this call. 85The second parameter may be a NULL pointer, in which case the trigger 86setting is not reported back. 87.It SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 88This option is used to enable or disable the two-argument version of 89the fts3_tokenizer() function which is part of the 90FTS3 full-text search engine extension. 91There should be two additional arguments. 92The first argument is an integer which is 0 to disable fts3_tokenizer() 93or positive to enable fts3_tokenizer() or negative to leave the setting 94unchanged. 95The second parameter is a pointer to an integer into which is written 960 or 1 to indicate whether fts3_tokenizer is disabled or enabled following 97this call. 98The second parameter may be a NULL pointer, in which case the new setting 99is not reported back. 100.It SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 101This option is used to enable or disable the sqlite3_load_extension() 102interface independently of the load_extension() SQL 103function. 104The sqlite3_enable_load_extension() 105API enables or disables both the C-API sqlite3_load_extension() 106and the SQL function load_extension(). 107There should be two additional arguments. 108When the first argument to this interface is 1, then only the C-API 109is enabled and the SQL function remains disabled. 110If the first argument to this interface is 0, then both the C-API and 111the SQL function are disabled. 112If the first argument is -1, then no changes are made to state of either 113the C-API or the SQL function. 114The second parameter is a pointer to an integer into which is written 1150 or 1 to indicate whether sqlite3_load_extension() 116interface is disabled or enabled following this call. 117The second parameter may be a NULL pointer, in which case the new setting 118is not reported back. 119.It SQLITE_DBCONFIG_MAINDBNAME 120This option is used to change the name of the "main" database schema. 121The sole argument is a pointer to a constant UTF8 string which will 122become the new schema name in place of "main". 123SQLite does not make a copy of the new main schema name string, so 124the application must ensure that the argument passed into this DBCONFIG 125option is unchanged until after the database connection closes. 126.It SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 127Usually, when a database in wal mode is closed or detached from a database 128handle, SQLite checks if this will mean that there are now no connections 129at all to the database. 130If so, it performs a checkpoint operation before closing the connection. 131This option may be used to override this behaviour. 132The first parameter passed to this operation is an integer - positive 133to disable checkpoints-on-close, or zero (the default) to enable them, 134and negative to leave the setting unchanged. 135The second parameter is a pointer to an integer into which is written 1360 or 1 to indicate whether checkpoints-on-close have been disabled 137- 0 if they are not disabled, 1 if they are. 138.It SQLITE_DBCONFIG_ENABLE_QPSG 139The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates the 140query planner stability guarantee 141(QPSG). 142When the QPSG is active, a single SQL query statement will always use 143the same algorithm regardless of values of bound parameters. 144The QPSG disables some query optimizations that look at the values 145of bound parameters, which can make some queries slower. 146But the QPSG has the advantage of more predictable behavior. 147With the QPSG active, SQLite will always use the same query plan in 148the field as was used during testing in the lab. 149The first argument to this setting is an integer which is 0 to disable 150the QPSG, positive to enable QPSG, or negative to leave the setting 151unchanged. 152The second parameter is a pointer to an integer into which is written 1530 or 1 to indicate whether the QPSG is disabled or enabled following 154this call. 155.It SQLITE_DBCONFIG_TRIGGER_EQP 156By default, the output of EXPLAIN QUERY PLAN commands does not include 157output for any operations performed by trigger programs. 158This option is used to set or clear (the default) a flag that governs 159this behavior. 160The first parameter passed to this operation is an integer - positive 161to enable output for trigger programs, or zero to disable it, or negative 162to leave the setting unchanged. 163The second parameter is a pointer to an integer into which is written 1640 or 1 to indicate whether output-for-triggers has been disabled - 1650 if it is not disabled, 1 if it is. 166.It SQLITE_DBCONFIG_RESET_DATABASE 167Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run VACUUM 168in order to reset a database back to an empty database with no schema 169and no content. 170The following process works even for a badly corrupted database file: 171.Bl -enum 172.It 173If the database connection is newly opened, make sure it has read the 174database schema by preparing then discarding some query against the 175database, or calling sqlite3_table_column_metadata(), ignoring any 176errors. 177This step is only necessary if the application desires to keep the 178database in WAL mode after the reset if it was in WAL mode before the 179reset. 180.It 181sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); 182.It 183sqlite3_exec(db, "VACUUM", 0, 0, 0); 184.It 185sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); 186.El 187.Pp 188Because resetting a database is destructive and irreversible, the process 189requires the use of this obscure API and multiple steps to help ensure 190that it does not happen by accident. 191.It SQLITE_DBCONFIG_DEFENSIVE 192The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the "defensive" 193flag for a database connection. 194When the defensive flag is enabled, language features that allow ordinary 195SQL to deliberately corrupt the database file are disabled. 196The disabled features include but are not limited to the following: 197.Bl -bullet 198.It 199The PRAGMA writable_schema=ON statement. 200.It 201Writes to the sqlite_dbpage virtual table. 202.It 203Direct writes to shadow tables. 204.El 205.Pp 206.El 207.Pp 208.Sh SEE ALSO 209.Xr sqlite3 3 , 210.Xr sqlite3_db_config 3 , 211.Xr sqlite3_db_status 3 , 212.Xr sqlite3_enable_load_extension 3 , 213.Xr sqlite3_exec 3 , 214.Xr sqlite3_load_extension 3 , 215.Xr sqlite3_malloc 3 , 216.Xr SQLITE_OK 3 , 217.Xr SQLITE_CONFIG_SINGLETHREAD 3 218