数据库连接配置选项

SQLite C 接口

数据库连接配置选项

#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 */

这些常量是可用的整数配置选项，可以作为第二个参数传递给sqlite3_db_config()接口。

在 SQLite 的未来版本中可能会添加新的配置选项。现有的配置选项可能会停止。应用程序应检查sqlite3_db_config()的返回码以确保调用有效。如果调用已停用或不受支持的配置选项，则sqlite3_db_config ()接口将返回非零错误代码。

SQLITE_DBCONFIG_LOOKASIDE

此选项采用三个附加参数来确定数据库连接的后备内存分配器配置。第一个参数（sqlite3_db_config()的第三个参数是指向用于后备内存的内存缓冲区的指针。SQLITE_DBCONFIG_LOOKASIDE 动词之后的第一个参数可能为 NULL，在这种情况下，SQLite 将使用sqlite3_malloc()自行分配后备缓冲区. 第二个参数是每个后备缓冲区槽的大小。第三个参数是槽的数量。第一个参数中缓冲区的大小必须大于或等于第二个和第三个参数的乘积。缓冲区必须与 8 字节边界对齐。如果 SQLITE_DBCONFIG_LOOKASIDE 的第二个参数不是 8 的倍数，它会在内部向下舍入到下一个更小的 8 倍数。数据库连接的后备内存配置只能在该连接当前未使用后备内存时更改，或者在换句话说，当 sqlite3_db_status (D, SQLITE_CONFIG_LOOKASIDE,...) 为零。当后备内存正在使用时，任何更改后备内存配置的尝试都会使配置保持不变并返回 SQLITE_BUSY。

SQLITE_DBCONFIG_ENABLE_FKEY

此选项用于启用或禁用外键约束的实施。应该有两个额外的参数。第一个参数是一个整数，为 0 表示禁用 FK 强制执行，为正表示启用 FK 强制执行或为负表示保持 FK 强制执行不变。第二个参数是一个指向整数的指针，写入 0 或 1 以指示在此调用之后 FK 强制执行是关闭还是打开。第二个参数可以是 NULL 指针，在这种情况下，不会报告 FK 强制设置。

SQLITE_DBCONFIG_ENABLE_TRIGGER

该选项用于启用或禁用触发器。应该有两个额外的参数。第一个参数是一个整数，0 表示禁用触发器，正数表示启用触发器，负数表示保持设置不变。第二个参数是指向一个整数的指针，写入 0 或 1 以指示在该调用之后触发器是被禁用还是被启用。第二个参数可以是 NULL 指针，在这种情况下不会报告触发器设置。

最初此选项禁用所有触发器。但是，从 SQLite 版本 3.35.0 开始，即使关闭此选项，仍然允许使用 TEMP 触发器。因此，换句话说，此选项现在仅禁用主数据库模式或 ATTACH 数据库模式中的触发器。

SQLITE_DBCONFIG_ENABLE_VIEW

此选项用于启用或禁用视图。应该有两个额外的参数。第一个参数是一个整数，0 表示禁用视图，正数表示启用视图，负数表示保持设置不变。第二个参数是一个指向整数的指针，其中写入 0 或 1 以指示在该调用之后视图是禁用还是启用。第二个参数可以是 NULL 指针，在这种情况下不会报告视图设置。

最初此选项禁用所有视图。但是，从 SQLite 版本 3.35.0 开始，即使关闭此选项，仍然允许使用 TEMP 视图。因此，换句话说，此选项现在仅禁用主数据库模式或 ATTACH 数据库模式中的视图。

SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

此选项用于启用或禁用 fts3_tokenizer()函数，该函数是 FTS3全文搜索引擎扩展的一部分。应该有两个额外的参数。第一个参数是一个整数，它是 0 以禁用 fts3_tokenizer() 或正数以启用 fts3_tokenizer() 或负数以保持设置不变。第二个参数是一个指向整数的指针，写入 0 或 1 以指示在此调用后 fts3_tokenizer 是禁用还是启用。第二个参数可能是一个 NULL 指针，在这种情况下，新设置不会被报告回来。

SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

此选项用于独立于load_extension() SQL 函数启用或禁用sqlite3_load_extension() 接口。sqlite3_enable_load_extension() API启用或禁用 C-API sqlite3_load_extension()和 SQL 函数load_extension(). 应该有两个额外的参数。当此接口的第一个参数为 1 时，则仅启用 C-API 而 SQL 功能保持禁用状态。如果此接口的第一个参数为 0，则 C-API 和 SQL 函数都被禁用。如果第一个参数是 -1，则不会对 C-API 或 SQL 函数的状态进行任何更改。第二个参数是一个指向整数的指针，写入 0 或 1 以指示在此调用后sqlite3_load_extension()接口是禁用还是启用。第二个参数可能是一个 NULL 指针，在这种情况下，新设置不会被报告回来。

SQLITE_DBCONFIG_MAINDBNAME

此选项用于更改“主”数据库模式的名称。唯一的参数是一个指向常量 UTF8 字符串的指针，该字符串将成为新模式名称以代替“main”。SQLite 不会复制新的主模式名称字符串，因此应用程序必须确保传递到此 DBCONFIG 选项的参数在数据库连接关闭之前保持不变。

SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

通常，当处于 wal 模式的数据库关闭或与数据库句柄分离时，SQLite 会检查这是否意味着现在根本没有与数据库的连接。如果是这样，它会在关闭连接之前执行检查点操作。此选项可用于覆盖此行为。传递给此操作的第一个参数是一个整数 - 正数表示禁用关闭检查点，或零（默认值）启用它们，负数表示保持设置不变。第二个参数是指向一个整数的指针，写入 0 或 1 以指示关闭时检查点是否已被禁用 - 如果未禁用则为 0，如果已禁用则为 1。

SQLITE_DBCONFIG_ENABLE_QPSG

SQLITE_DBCONFIG_ENABLE_QPSG 选项激活或停用查询规划器稳定性保证(QPSG)。当 QPSG 处于活动状态时，无论绑定参数的值如何，单个 SQL 查询语句将始终使用相同的算法. QPSG 禁用了一些查看绑定参数值的查询优化，这会使某些查询变慢。但 QPSG 的优势在于行为更可预测。在 QPSG 处于活动状态时，SQLite 将始终在现场使用与在实验室测试期间使用的查询计划相同的查询计划。此设置的第一个参数是一个整数，0 表示禁用 QPSG，正数表示启用 QPSG，负数表示保持设置不变。第二个参数是一个指向整数的指针，写入 0 或 1 以指示在此调用后 QPSG 是禁用还是启用。

SQLITE_DBCONFIG_TRIGGER_EQP

默认情况下，EXPLAIN QUERY PLAN 命令的输出不包括触发器程序执行的任何操作的输出。此选项用于设置或清除（默认）控制此行为的标志。传递给此操作的第一个参数是一个整数 - 正数表示启用触发程序的输出，零表示禁用它，负数表示保持设置不变。第二个参数是一个指向整数的指针，其中写入 0 或 1 以指示触发器输出是否已被禁用 - 如果未禁用，则为 0，如果已禁用，则为 1。

SQLITE_DBCONFIG_RESET_DATABASE

设置 SQLITE_DBCONFIG_RESET_DATABASE 标志，然后运行 VACUUM以将数据库重置回没有模式和内容的空数据库。以下过程甚至适用于严重损坏的数据库文件：

如果数据库连接是新打开的，请通过准备然后丢弃对数据库的一些查询或调用 sqlite3_table_column_metadata() 来确保它已读取数据库模式，忽略任何错误。仅当应用程序希望在重置后将数据库保持在 WAL 模式（如果重置前处于 WAL 模式）时才需要执行此步骤。
sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
sqlite3_exec (db, "真空", 0, 0, 0);
sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);

由于重置数据库具有破坏性和不可逆性，因此该过程需要使用这个晦涩的 API 和多个步骤来帮助确保不会意外发生。

SQLITE_DBCONFIG_DEFENSIVE

SQLITE_DBCONFIG_DEFENSIVE 选项激活或停用数据库连接的“防御”标志。启用防御标志后，将禁用允许普通 SQL 故意损坏数据库文件的语言功能。禁用的功能包括但不限于以下：

PRAGMA writable_schema=ON语句。
PRAGMA journal_mode =OFF语句。
写入sqlite_dbpage虚拟表。
直接写入影子表。

SQLITE_DBCONFIG_WRITABLE_SCHEMA

SQLITE_DBCONFIG_WRITABLE_SCHEMA 选项激活或停用“writable_schema”标志。这具有相同的效果，并且在逻辑上等同于设置PRAGMA writable_schema=ON或PRAGMA writable_schema=OFF。此设置的第一个参数是一个整数，0 表示禁用 writable_schema，正数表示启用 writable_schema，负数表示保持设置不变。第二个参数是一个指向整数的指针，写入 0 或 1 以指示在此调用后 writable_schema 是启用还是禁用。

SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 选项激活或停用ALTER TABLE RENAME命令的遗留行为，使其行为与版本 3.24.0 (2018-06-04) 之前一样。有关其他信息，请参阅ALTER TABLE RENAME 文档中的“兼容性声明” 。也可以使用PRAGMA legacy_alter_table语句打开和关闭此功能。

SQLITE_DBCONFIG_DQS_DML

SQLITE_DBCONFIG_DQS_DML 选项仅针对 DML 语句（即 DELETE、INSERT、SELECT 和 UPDATE 语句）激活或停用遗留的双引号字符串文字错误功能。此设置的默认值由-DSQLITE_DQS 编译时选项确定。

SQLITE_DBCONFIG_DQS_DDL

SQLITE_DBCONFIG_DQS 选项激活或停用DDL 语句（例如 CREATE TABLE 和 CREATE INDEX）的遗留双引号字符串文字错误功能。此设置的默认值由-DSQLITE_DQS 编译时选项确定。

SQLITE_DBCONFIG_TRUSTED_SCHEMA

SQLITE_DBCONFIG_TRUSTED_SCHEMA 选项告诉 SQLite 假设数据库模式未被恶意内容污染。当 SQLITE_DBCONFIG_TRUSTED_SCHEMA 选项被禁用时，SQLite 采取额外的防御措施来保护应用程序免受伤害，包括：

禁止在触发器、视图、CHECK 约束、DEFAULT 子句、表达式索引、部分索引或生成的列中使用 SQL 函数，除非这些函数被标记为SQLITE_INNOCUOUS。
禁止在触发器或视图中使用虚拟表，除非这些虚拟表被标记为SQLITE_VTAB_INNOCUOUS。

此设置默认为“开”以实现旧版兼容性，但建议所有应用程序尽可能将其关闭。也可以使用PRAGMA trusted_schema语句控制此设置。

SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 选项激活或停用旧文件格式标志。激活时，此标志会导致所有新创建的数据库文件的模式格式版本号（在数据库头的偏移量 44 处找到的 4 字节整数）为 1。这反过来意味着生成的数据库文件将是可读和可写的通过任何 SQLite 版本回到 3.0.0 (2004-06-18)。如果没有此设置，SQLite 3.3.0 (2006-01-11) 之前的版本通常无法理解新创建的数据库。正如这些话所写的那样，现在几乎不需要生成一直兼容到 3.0.0 版本的数据库文件，因此这个设置几乎没有实际用处，但提供它是为了让 SQLite 可以继续要求能够生成与版本 3 兼容的新数据库文件。

请注意，当 SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 设置打开时，VACUUM命令在尝试处理具有生成的列和降序索引的表时将失败并出现一个模糊的错误。这不被认为是一个错误，因为 SQLite 版本 3.3.0 和更早版本不支持生成的列或降序索引。

另请参阅对象、常量和函数的列表。