.Dd December 19, 2018
.Dt SQLITE_DBCONFIG_MAINDBNAME 3
.Os
.Sh NAME
.Nm SQLITE_DBCONFIG_MAINDBNAME ,
.Nm SQLITE_DBCONFIG_LOOKASIDE ,
.Nm SQLITE_DBCONFIG_ENABLE_FKEY ,
.Nm SQLITE_DBCONFIG_ENABLE_TRIGGER ,
.Nm SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER ,
.Nm SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION ,
.Nm SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE ,
.Nm SQLITE_DBCONFIG_ENABLE_QPSG ,
.Nm SQLITE_DBCONFIG_TRIGGER_EQP ,
.Nm SQLITE_DBCONFIG_RESET_DATABASE ,
.Nm SQLITE_DBCONFIG_DEFENSIVE ,
.Nm SQLITE_DBCONFIG_MAX
.Nd Database Connection Configuration Options
.Sh SYNOPSIS
.Fd #define SQLITE_DBCONFIG_MAINDBNAME
.Fd #define SQLITE_DBCONFIG_LOOKASIDE
.Fd #define SQLITE_DBCONFIG_ENABLE_FKEY
.Fd #define SQLITE_DBCONFIG_ENABLE_TRIGGER
.Fd #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
.Fd #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
.Fd #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
.Fd #define SQLITE_DBCONFIG_ENABLE_QPSG
.Fd #define SQLITE_DBCONFIG_TRIGGER_EQP
.Fd #define SQLITE_DBCONFIG_RESET_DATABASE
.Fd #define SQLITE_DBCONFIG_DEFENSIVE
.Fd #define SQLITE_DBCONFIG_MAX
.Sh DESCRIPTION
These constants are the available integer configuration options that
can be passed as the second argument to the sqlite3_db_config()
interface.
.Pp
New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued.
Applications should check the return code from sqlite3_db_config()
to make sure that the call worked.
The sqlite3_db_config() interface will return a
non-zero error code if a discontinued or unsupported configuration
option is invoked.
.Bl -tag -width Ds
.It SQLITE_DBCONFIG_LOOKASIDE
This option takes three additional arguments that determine the lookaside memory allocator
configuration for the database connection.
The first argument (the third parameter to sqlite3_db_config()
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 sqlite3_malloc().
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 sqlite3_db_status(D,SQLITE_CONFIG_LOOKASIDE,...)
is zero.
Any attempt to change the lookaside memory configuration when lookaside
memory is in use leaves the configuration unchanged and returns SQLITE_BUSY.
.It SQLITE_DBCONFIG_ENABLE_FKEY
This option is used to enable or disable the enforcement of foreign key constraints.
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.
.It SQLITE_DBCONFIG_ENABLE_TRIGGER
This option is used to enable or disable  triggers.
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.
.It SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
This option is used to enable or disable the two-argument version of
the fts3_tokenizer() function which is part of the
FTS3 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.
.It SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
This option is used to enable or disable the sqlite3_load_extension()
interface independently of the load_extension() SQL
function.
The sqlite3_enable_load_extension()
API enables or disables both the C-API sqlite3_load_extension()
and the SQL function load_extension().
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 sqlite3_load_extension()
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.
.It SQLITE_DBCONFIG_MAINDBNAME
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.
.It SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
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.
.It SQLITE_DBCONFIG_ENABLE_QPSG
The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates the
query planner stability guarantee
(QPSG).
When the QPSG is active, a single SQL query statement will always use
the same algorithm regardless of values of bound parameters.
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.
.It SQLITE_DBCONFIG_TRIGGER_EQP
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.
.It SQLITE_DBCONFIG_RESET_DATABASE
Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run VACUUM
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:
.Bl -enum
.It
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.
.It
sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); 
.It
sqlite3_exec(db, "VACUUM", 0, 0, 0); 
.It
sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); 
.El
.Pp
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.
.It SQLITE_DBCONFIG_DEFENSIVE
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:
.Bl -bullet
.It
The PRAGMA writable_schema=ON statement.
.It
Writes to the sqlite_dbpage virtual table.
.It
Direct writes to shadow tables.
.El
.Pp
.El
.Pp
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_db_config 3 ,
.Xr sqlite3_db_status 3 ,
.Xr sqlite3_enable_load_extension 3 ,
.Xr sqlite3_exec 3 ,
.Xr sqlite3_load_extension 3 ,
.Xr sqlite3_malloc 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_CONFIG_SINGLETHREAD 3