1.Dd January 24, 2024 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_WRITABLE_SCHEMA , 17.Nm SQLITE_DBCONFIG_LEGACY_ALTER_TABLE , 18.Nm SQLITE_DBCONFIG_DQS_DML , 19.Nm SQLITE_DBCONFIG_DQS_DDL , 20.Nm SQLITE_DBCONFIG_ENABLE_VIEW , 21.Nm SQLITE_DBCONFIG_LEGACY_FILE_FORMAT , 22.Nm SQLITE_DBCONFIG_TRUSTED_SCHEMA , 23.Nm SQLITE_DBCONFIG_STMT_SCANSTATUS , 24.Nm SQLITE_DBCONFIG_REVERSE_SCANORDER , 25.Nm SQLITE_DBCONFIG_MAX 26.Nd database connection configuration options 27.Sh SYNOPSIS 28.In sqlite3.h 29.Fd #define SQLITE_DBCONFIG_MAINDBNAME 30.Fd #define SQLITE_DBCONFIG_LOOKASIDE 31.Fd #define SQLITE_DBCONFIG_ENABLE_FKEY 32.Fd #define SQLITE_DBCONFIG_ENABLE_TRIGGER 33.Fd #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 34.Fd #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 35.Fd #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 36.Fd #define SQLITE_DBCONFIG_ENABLE_QPSG 37.Fd #define SQLITE_DBCONFIG_TRIGGER_EQP 38.Fd #define SQLITE_DBCONFIG_RESET_DATABASE 39.Fd #define SQLITE_DBCONFIG_DEFENSIVE 40.Fd #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 41.Fd #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 42.Fd #define SQLITE_DBCONFIG_DQS_DML 43.Fd #define SQLITE_DBCONFIG_DQS_DDL 44.Fd #define SQLITE_DBCONFIG_ENABLE_VIEW 45.Fd #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 46.Fd #define SQLITE_DBCONFIG_TRUSTED_SCHEMA 47.Fd #define SQLITE_DBCONFIG_STMT_SCANSTATUS 48.Fd #define SQLITE_DBCONFIG_REVERSE_SCANORDER 49.Fd #define SQLITE_DBCONFIG_MAX 50.Sh DESCRIPTION 51These constants are the available integer configuration options that 52can be passed as the second argument to the 53.Fn sqlite3_db_config 54interface. 55.Pp 56New configuration options may be added in future releases of SQLite. 57Existing configuration options might be discontinued. 58Applications should check the return code from 59.Fn sqlite3_db_config 60to make sure that the call worked. 61The 62.Fn sqlite3_db_config 63interface will return a non-zero error code if a discontinued 64or unsupported configuration option is invoked. 65.Bl -tag -width Ds 66.It SQLITE_DBCONFIG_LOOKASIDE 67This option takes three additional arguments that determine the lookaside memory allocator 68configuration for the database connection. 69The first argument (the third parameter to 70.Fn sqlite3_db_config 71is a pointer to a memory buffer to use for lookaside memory. 72The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be 73NULL in which case SQLite will allocate the lookaside buffer itself 74using 75.Fn sqlite3_malloc . 76The second argument is the size of each lookaside buffer slot. 77The third argument is the number of slots. 78The size of the buffer in the first argument must be greater than or 79equal to the product of the second and third arguments. 80The buffer must be aligned to an 8-byte boundary. 81If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple 82of 8, it is internally rounded down to the next smaller multiple of 838. 84The lookaside memory configuration for a database connection can only 85be changed when that connection is not currently using lookaside memory, 86or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_DBSTATUS_LOOKASIDE_USED,...) 87is zero. 88Any attempt to change the lookaside memory configuration when lookaside 89memory is in use leaves the configuration unchanged and returns SQLITE_BUSY. 90.It SQLITE_DBCONFIG_ENABLE_FKEY 91This option is used to enable or disable the enforcement of foreign key constraints. 92There should be two additional arguments. 93The first argument is an integer which is 0 to disable FK enforcement, 94positive to enable FK enforcement or negative to leave FK enforcement 95unchanged. 96The second parameter is a pointer to an integer into which is written 970 or 1 to indicate whether FK enforcement is off or on following this 98call. 99The second parameter may be a NULL pointer, in which case the FK enforcement 100setting is not reported back. 101.It SQLITE_DBCONFIG_ENABLE_TRIGGER 102This option is used to enable or disable triggers. 103There should be two additional arguments. 104The first argument is an integer which is 0 to disable triggers, positive 105to enable triggers or negative to leave the setting unchanged. 106The second parameter is a pointer to an integer into which is written 1070 or 1 to indicate whether triggers are disabled or enabled following 108this call. 109The second parameter may be a NULL pointer, in which case the trigger 110setting is not reported back. 111.Pp 112Originally this option disabled all triggers. 113However, since SQLite version 3.35.0, TEMP triggers are still allowed 114even if this option is off. 115So, in other words, this option now only disables triggers in the main 116database schema or in the schemas of ATTACH-ed databases. 117.It SQLITE_DBCONFIG_ENABLE_VIEW 118This option is used to enable or disable views. 119There should be two additional arguments. 120The first argument is an integer which is 0 to disable views, positive 121to enable views or negative to leave the setting unchanged. 122The second parameter is a pointer to an integer into which is written 1230 or 1 to indicate whether views are disabled or enabled following 124this call. 125The second parameter may be a NULL pointer, in which case the view 126setting is not reported back. 127.Pp 128Originally this option disabled all views. 129However, since SQLite version 3.35.0, TEMP views are still allowed 130even if this option is off. 131So, in other words, this option now only disables views in the main 132database schema or in the schemas of ATTACH-ed databases. 133.It SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 134This option is used to enable or disable the 135.Fn fts3_tokenizer 136function which is part of the FTS3 full-text search engine extension. 137There should be two additional arguments. 138The first argument is an integer which is 0 to disable fts3_tokenizer() 139or positive to enable fts3_tokenizer() or negative to leave the setting 140unchanged. 141The second parameter is a pointer to an integer into which is written 1420 or 1 to indicate whether fts3_tokenizer is disabled or enabled following 143this call. 144The second parameter may be a NULL pointer, in which case the new setting 145is not reported back. 146.It SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 147This option is used to enable or disable the 148.Fn sqlite3_load_extension 149interface independently of the 150.Fn load_extension 151SQL function. 152The 153.Fn sqlite3_enable_load_extension 154API enables or disables both the C-API 155.Fn sqlite3_load_extension 156and the SQL function 157.Fn load_extension . 158There should be two additional arguments. 159When the first argument to this interface is 1, then only the C-API 160is enabled and the SQL function remains disabled. 161If the first argument to this interface is 0, then both the C-API and 162the SQL function are disabled. 163If the first argument is -1, then no changes are made to state of either 164the C-API or the SQL function. 165The second parameter is a pointer to an integer into which is written 1660 or 1 to indicate whether 167.Fn sqlite3_load_extension 168interface is disabled or enabled following this call. 169The second parameter may be a NULL pointer, in which case the new setting 170is not reported back. 171.It SQLITE_DBCONFIG_MAINDBNAME 172This option is used to change the name of the "main" database schema. 173The sole argument is a pointer to a constant UTF8 string which will 174become the new schema name in place of "main". 175SQLite does not make a copy of the new main schema name string, so 176the application must ensure that the argument passed into this DBCONFIG 177option is unchanged until after the database connection closes. 178.It SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 179Usually, when a database in wal mode is closed or detached from a database 180handle, SQLite checks if this will mean that there are now no connections 181at all to the database. 182If so, it performs a checkpoint operation before closing the connection. 183This option may be used to override this behavior. 184The first parameter passed to this operation is an integer - positive 185to disable checkpoints-on-close, or zero (the default) to enable them, 186and negative to leave the setting unchanged. 187The second parameter is a pointer to an integer into which is written 1880 or 1 to indicate whether checkpoints-on-close have been disabled 189- 0 if they are not disabled, 1 if they are. 190.It SQLITE_DBCONFIG_ENABLE_QPSG 191The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates the 192query planner stability guarantee 193(QPSG). 194When the QPSG is active, a single SQL query statement will always use 195the same algorithm regardless of values of bound parameters. 196The QPSG disables some query optimizations that look at the values 197of bound parameters, which can make some queries slower. 198But the QPSG has the advantage of more predictable behavior. 199With the QPSG active, SQLite will always use the same query plan in 200the field as was used during testing in the lab. 201The first argument to this setting is an integer which is 0 to disable 202the QPSG, positive to enable QPSG, or negative to leave the setting 203unchanged. 204The second parameter is a pointer to an integer into which is written 2050 or 1 to indicate whether the QPSG is disabled or enabled following 206this call. 207.It SQLITE_DBCONFIG_TRIGGER_EQP 208By default, the output of EXPLAIN QUERY PLAN commands does not include 209output for any operations performed by trigger programs. 210This option is used to set or clear (the default) a flag that governs 211this behavior. 212The first parameter passed to this operation is an integer - positive 213to enable output for trigger programs, or zero to disable it, or negative 214to leave the setting unchanged. 215The second parameter is a pointer to an integer into which is written 2160 or 1 to indicate whether output-for-triggers has been disabled - 2170 if it is not disabled, 1 if it is. 218.It SQLITE_DBCONFIG_RESET_DATABASE 219Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run VACUUM 220in order to reset a database back to an empty database with no schema 221and no content. 222The following process works even for a badly corrupted database file: 223.Bl -enum 224.It 225If the database connection is newly opened, make sure it has read the 226database schema by preparing then discarding some query against the 227database, or calling sqlite3_table_column_metadata(), ignoring any 228errors. 229This step is only necessary if the application desires to keep the 230database in WAL mode after the reset if it was in WAL mode before the 231reset. 232.It 233sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); 234.It 235sqlite3_exec(db, "VACUUM", 0, 0, 0); 236.It 237sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); 238.El 239.Pp 240Because resetting a database is destructive and irreversible, the process 241requires the use of this obscure API and multiple steps to help ensure 242that it does not happen by accident. 243Because this feature must be capable of resetting corrupt databases, 244and shutting down virtual tables may require access to that corrupt 245storage, the library must abandon any installed virtual tables without 246calling their xDestroy() methods. 247.It SQLITE_DBCONFIG_DEFENSIVE 248The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the "defensive" 249flag for a database connection. 250When the defensive flag is enabled, language features that allow ordinary 251SQL to deliberately corrupt the database file are disabled. 252The disabled features include but are not limited to the following: 253.Bl -bullet 254.It 255The PRAGMA writable_schema=ON statement. 256.It 257The PRAGMA journal_mode=OFF statement. 258.It 259The PRAGMA schema_version=N statement. 260.It 261Writes to the sqlite_dbpage virtual table. 262.It 263Direct writes to shadow tables. 264.El 265.Pp 266.It SQLITE_DBCONFIG_WRITABLE_SCHEMA 267The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates 268the "writable_schema" flag. 269This has the same effect and is logically equivalent to setting PRAGMA writable_schema=ON 270or PRAGMA writable_schema=OFF. 271The first argument to this setting is an integer which is 0 to disable 272the writable_schema, positive to enable writable_schema, or negative 273to leave the setting unchanged. 274The second parameter is a pointer to an integer into which is written 2750 or 1 to indicate whether the writable_schema is enabled or disabled 276following this call. 277.It SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 278The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates 279the legacy behavior of the ALTER TABLE RENAME command 280such it behaves as it did prior to version 3.24.0 (2018-06-04). 281See the "Compatibility Notice" on the ALTER TABLE RENAME documentation 282for additional information. 283This feature can also be turned on and off using the PRAGMA legacy_alter_table 284statement. 285.It SQLITE_DBCONFIG_DQS_DML 286The SQLITE_DBCONFIG_DQS_DML option activates or deactivates the legacy 287double-quoted string literal misfeature 288for DML statements only, that is DELETE, INSERT, SELECT, and UPDATE 289statements. 290The default value of this setting is determined by the -DSQLITE_DQS 291compile-time option. 292.It SQLITE_DBCONFIG_DQS_DDL 293The SQLITE_DBCONFIG_DQS option activates or deactivates the legacy 294double-quoted string literal misfeature 295for DDL statements, such as CREATE TABLE and CREATE INDEX. 296The default value of this setting is determined by the -DSQLITE_DQS 297compile-time option. 298.It SQLITE_DBCONFIG_TRUSTED_SCHEMA 299The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to assume that 300database schemas are untainted by malicious content. 301When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite 302takes additional defensive steps to protect the application from harm 303including: 304.Bl -bullet 305.It 306Prohibit the use of SQL functions inside triggers, views, CHECK constraints, 307DEFAULT clauses, expression indexes, partial indexes, or generated 308columns unless those functions are tagged with SQLITE_INNOCUOUS. 309.It 310Prohibit the use of virtual tables inside of triggers or views unless 311those virtual tables are tagged with SQLITE_VTAB_INNOCUOUS. 312.El 313.Pp 314This setting defaults to "on" for legacy compatibility, however all 315applications are advised to turn it off if possible. 316This setting can also be controlled using the PRAGMA trusted_schema 317statement. 318.It SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 319The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates 320the legacy file format flag. 321When activated, this flag causes all newly created database file to 322have a schema format version number (the 4-byte integer found at offset 32344 into the database header) of 1. 324This in turn means that the resulting database file will be readable 325and writable by any SQLite version back to 3.0.0 (dateof:3.0.0). 326Without this setting, newly created databases are generally not understandable 327by SQLite versions prior to 3.3.0 (dateof:3.3.0). 328As these words are written, there is now scarcely any need to generate 329database files that are compatible all the way back to version 3.0.0, 330and so this setting is of little practical use, but is provided so 331that SQLite can continue to claim the ability to generate new database 332files that are compatible with version 3.0.0. 333.Pp 334Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on, 335the VACUUM command will fail with an obscure error when attempting 336to process a table with generated columns and a descending index. 337This is not considered a bug since SQLite versions 3.3.0 and earlier 338do not support either generated columns or descending indexes. 339.It SQLITE_DBCONFIG_STMT_SCANSTATUS 340The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in SQLITE_ENABLE_STMT_SCANSTATUS 341builds. 342In this case, it sets or clears a flag that enables collection of the 343sqlite3_stmt_scanstatus_v2() statistics. 344For statistics to be collected, the flag must be set on the database 345handle both when the SQL statement is prepared and when it is stepped. 346The flag is set (collection of statistics is enabled) by default. 347This option takes two arguments: an integer and a pointer to an integer.. 348The first argument is 1, 0, or -1 to enable, disable, or leave unchanged 349the statement scanstatus option. 350If the second argument is not NULL, then the value of the statement 351scanstatus setting after processing the first argument is written into 352the integer that the second argument points to. 353.It SQLITE_DBCONFIG_REVERSE_SCANORDER 354The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order 355in which tables and indexes are scanned so that the scans start at 356the end and work toward the beginning rather than starting at the beginning 357and working toward the end. 358Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the same as setting PRAGMA reverse_unordered_selects. 359This option takes two arguments which are an integer and a pointer 360to an integer. 361The first argument is 1, 0, or -1 to enable, disable, or leave unchanged 362the reverse scan order flag, respectively. 363If the second argument is not NULL, then 0 or 1 is written into the 364integer that the second argument points to depending on if the reverse 365scan order flag is set after processing the first argument. 366.El 367.Pp 368.Sh IMPLEMENTATION NOTES 369These declarations were extracted from the 370interface documentation at line 2177. 371.Bd -literal 372#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ 373#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ 374#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ 375#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ 376#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ 377#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ 378#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ 379#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ 380#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ 381#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ 382#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ 383#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ 384#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ 385#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ 386#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ 387#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */ 388#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */ 389#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */ 390#define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */ 391#define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */ 392#define SQLITE_DBCONFIG_MAX 1019 /* Largest DBCONFIG */ 393.Ed 394.Sh SEE ALSO 395.Xr sqlite3 3 , 396.Xr sqlite3_db_config 3 , 397.Xr sqlite3_db_status 3 , 398.Xr sqlite3_enable_load_extension 3 , 399.Xr sqlite3_exec 3 , 400.Xr sqlite3_load_extension 3 , 401.Xr sqlite3_malloc 3 , 402.Xr SQLITE_DBSTATUS_LOOKASIDE_USED 3 , 403.Xr SQLITE_DETERMINISTIC 3 , 404.Xr SQLITE_OK 3 , 405.Xr SQLITE_VTAB_CONSTRAINT_SUPPORT 3 406