SQLite C 接口
配置选项
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */ #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ #define SQLITE_CONFIG_PCACHE 14 /* no-op */ #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ #define SQLITE_CONFIG_URI 17 /* int */ #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
这些常量是可用的整数配置选项，可以作为第一个参数传递给sqlite3_config()接口。
在 SQLite 的未来版本中可能会添加新的配置选项。现有的配置选项可能会停止。应用程序应检查sqlite3_config()的返回码以确保调用有效。如果调用已停用或不受支持的配置选项，则sqlite3_config ()接口将返回非零错误代码。
- SQLITE_CONFIG_SINGLETHREAD
- 此选项没有参数。此选项将 线程模式设置为单线程。换句话说，它禁用所有互斥并将 SQLite 置于只能由单个线程使用的模式。如果使用SQLITE_THREADSAFE=0编译时选项编译 SQLite，则无法更改线程模式的默认值单线程，因此如果使用 SQLITE_CONFIG_SINGLETHREAD 配置选项调用，sqlite3_config()将返回 SQLITE_ERROR 。
- SQLITE_CONFIG_MULTITHREAD
- 此选项没有参数。此选项将 线程模式设置为多线程。换句话说，它禁用了数据库连接和准备好的语句对象上的互斥。该应用程序负责序列化对 数据库连接和准备好的语句的访问。但是启用了其他互斥锁，这样只要没有两个线程同时尝试使用同一个 数据库连接，SQLite 就可以在多线程环境中安全使用。如果使用SQLITE_THREADSAFE=0编译时选项编译 SQLite，则无法设置多线程线程模式，并且 如果使用 SQLITE_CONFIG_MULTITHREAD 配置选项调用，sqlite3_config()将返回SQLITE_ERROR 。
- SQLITE_CONFIG_SERIALIZED
- 此选项没有参数。此选项将 线程模式设置为序列化。换句话说，此选项启用所有互斥锁，包括数据库连接和准备好的语句对象上的递归互斥锁。在这种模式下（当使用SQLITE_THREADSAFE=1编译 SQLite 时，这是默认模式 ）SQLite 库本身将序列化对数据库连接和准备语句的访问，以便应用程序可以在不同线程中自由使用相同的数据库连接或相同的准备语句同时。如果 SQLite 是用SQLITE_THREADSAFE=0编译的编译时选项则无法设置序列化线程模式， 如果使用 SQLITE_CONFIG_SERIALIZED 配置选项调用，sqlite3_config()将返回SQLITE_ERROR 。
- SQLITE_CONFIG_MALLOC
- SQLITE_CONFIG_MALLOC 选项采用单个参数，该参数是指向sqlite3_mem_methods结构实例的指针。该参数指定替代的低级内存分配例程，用于代替 SQLite 中内置的内存分配例程。在sqlite3_config()调用返回之前， SQLite 会制作自己的sqlite3_mem_methods结构内容的私有副本。
- SQLITE_CONFIG_GETMALLOC
- SQLITE_CONFIG_GETMALLOC 选项采用单个参数，该参数是指向sqlite3_mem_methods结构实例的指针。sqlite3_mem_methods 结构中填充了当前定义的内存分配例程。例如，此选项可用于使用模拟内存分配失败或跟踪内存使用情况的包装器来重载默认内存分配例程。
- SQLITE_CONFIG_SMALL_MALLOC
- SQLITE_CONFIG_SMALL_MALLOC 选项采用 int 类型的单个参数，解释为布尔值，如果为真，则向 SQLite 提示它应尽可能避免大内存分配。如果可以自由分配大量内存，SQLite 将运行得更快，但某些应用程序可能更愿意运行得更慢，以换取如果避免大量分配可能出现的内存碎片保证。这个提示通常是关闭的。
- SQLITE_CONFIG_MEMSTATUS
- SQLITE_CONFIG_MEMSTATUS 选项采用 int 类型的单个参数，解释为布尔值，它启用或禁用内存分配统计信息的收集。当禁用内存分配统计信息时，以下 SQLite 接口将变得不可操作：
- sqlite3_hard_heap_limit64()
- sqlite3_memory_used()
- sqlite3_memory_highwater()
- sqlite3_soft_heap_limit64()
- sqlite3_status64()
- SQLITE_CONFIG_SCRATCH
- SQLITE_CONFIG_SCRATCH 选项不再使用。
- SQLITE_CONFIG_PAGECACHE
- SQLITE_CONFIG_PAGECACHE 选项指定一个内存池，SQLite 可以将其用于具有默认页面缓存实现的数据库页面缓存。如果应用程序定义的页面缓存实现是使用SQLITE_CONFIG_PCACHE2加载的，则此配置选项是空操作。SQLITE_CONFIG_PAGECACHE 有三个参数：指向 8 字节对齐内存 (pMem) 的指针、每个页面缓存行的大小 (sz) 和缓存行数 (N)。sz 参数应该是最大数据库页面的大小（512 和 65536 之间的 2 的幂）加上每个页面标题的一些额外字节。可以使用SQLITE_CONFIG_PCACHE_HDRSZ确定页眉所需的额外字节数. 除了浪费内存之外，sz 参数大于必要值是无害的。pMem 参数必须是 NULL 指针或指向至少 sz*N 字节的 8 字节对齐内存块的指针，否则后续行为未定义。当 pMem 不为 NULL 时，SQLite 将努力使用提供的内存来满足页面缓存需求，如果页面缓存行大于 sz 字节或所有 pMem 缓冲区都已耗尽，则回退到sqlite3_malloc() 。如果 pMem 为 NULL 且 N 非零，则每个数据库连接都会从sqlite3_malloc()为页面缓存内存进行初始批量分配如果 N 为正数，则足以用于 N 个缓存行；如果 N 为负数，则为 -1024*N 字节，. 如果需要超出初始分配提供的额外页面缓存内存，则 SQLite 会为每个额外的缓存行单独转到sqlite3_malloc() 。
- SQLITE_CONFIG_HEAP
- SQLITE_CONFIG_HEAP 选项指定一个静态内存缓冲区，SQLite 将使用它来满足SQLITE_CONFIG_PAGECACHE提供的所有动态内存分配需求。SQLITE_CONFIG_HEAP 选项仅在使用SQLITE_ENABLE_MEMSYS3或SQLITE_ENABLE_MEMSYS5编译 SQLite 时可用，否则返回 SQLITE_ERROR。SQLITE_CONFIG_HEAP 有三个参数：指向内存的 8 字节对齐指针、内存缓冲区中的字节数和最小分配大小。如果第一个指针（内存指针）为 NULL，则 SQLite 恢复使用其默认内存分配器（系统 malloc() 实现），撤消之前对SQLITE_CONFIG_MALLOC的任何调用. 如果内存指针不为 NULL，则使用替代内存分配器来处理所有 SQLite 内存分配需求。第一个指针（内存指针）必须与 8 字节边界对齐，否则 SQLite 的后续行为将是未定义的。最小分配大小上限为 2**12。最小分配大小的合理值是 2**5 到 2**8。
- SQLITE_CONFIG_MUTEX
- SQLITE_CONFIG_MUTEX 选项采用单个参数，该参数是指向sqlite3_mutex_methods结构实例的指针。该参数指定替代的低级互斥例程，用于替代 SQLite 中内置的互斥例程。在对sqlite3_config()的调用返回之前， SQLite 会复制sqlite3_mutex_methods结构 的内容。如果 SQLite 是使用SQLITE_THREADSAFE=0编译时选项编译的，那么整个互斥子系统将从构建中省略，因此使用 SQLITE_CONFIG_MUTEX 配置选项调用 sqlite3_config()将返回SQLITE_ERROR。
- SQLITE_CONFIG_GETMUTEX
- SQLITE_CONFIG_GETMUTEX 选项采用单个参数，该参数是指向sqlite3_mutex_methods结构实例的指针。sqlite3_mutex_methods 结构填充了当前定义的互斥例程。 例如，此选项可用于使用用于跟踪互斥使用情况以进行性能分析或测试的包装器来重载默认互斥分配例程。如果 SQLite 是使用SQLITE_THREADSAFE=0编译时选项编译的，那么整个互斥子系统将从构建中省略，因此使用 SQLITE_CONFIG_GETMUTEX 配置选项调用 sqlite3_config()将返回SQLITE_ERROR。
- SQLITE_CONFIG_LOOKASIDE
- SQLITE_CONFIG_LOOKASIDE 选项采用两个参数来确定每个数据库连接上后备内存的默认大小。第一个参数是每个后备缓冲区槽的大小，第二个是分配给每个数据库连接的槽数。SQLITE_CONFIG_LOOKASIDE 设置默认后备大小。sqlite3_db_config()的SQLITE_DBCONFIG_LOOKASIDE 选项可用于更改单个连接的后备配置。
- SQLITE_CONFIG_PCACHE2
- SQLITE_CONFIG_PCACHE2 选项采用单个参数，该参数是指向sqlite3_pcache_methods2对象的指针。该对象指定自定义页面缓存实现的接口。SQLite 复制了sqlite3_pcache_methods2对象。
- SQLITE_CONFIG_GETPCACHE2
- SQLITE_CONFIG_GETPCACHE2 选项采用单个参数，该参数是指向sqlite3_pcache_methods2对象的指针。SQLite 将当前页面缓存实现的副本复制到该对象中。
- SQLITE_CONFIG_LOG
- SQLITE_CONFIG_LOG 选项用于配置 SQLite 全局错误日志。（SQLITE_CONFIG_LOG 选项有两个参数：一个指向调用签名为 void(*)(void*,int,const char*) 的函数的指针，以及一个指向 void 的指针。如果函数指针不为 NULL，则调用它通过sqlite3_log()处理每个日志记录事件。如果函数指针为 NULL，则sqlite3_log()接口变为无操作。作为 SQLITE_CONFIG_LOG 的第二个参数的空指针作为第一个参数传递给应用程序定义的每当调用该函数时记录器函数。记录器函数的第二个参数是相应 sqlite3_log()调用的第一个参数的副本，旨在成为结果代码或 扩展结果代码。传递给记录器的第三个参数是通过sqlite3_snprintf()格式化后的日志消息。SQLite 日志记录接口是不可重入的；应用程序提供的记录器函数不得调用任何 SQLite 接口。在多线程应用程序中，应用程序定义的记录器函数必须是线程安全的。
- SQLITE_CONFIG_URI
- SQLITE_CONFIG_URI 选项接受一个 int 类型的参数。如果非零，则全局启用 URI 处理。如果参数为零，则全局禁用 URI 处理。如果全局启用 URI 处理，则所有传递给sqlite3_open()、sqlite3_open_v2()、 sqlite3_open16()或指定为ATTACH命令的一部分的文件名都被解释为 URI，无论在打开数据库连接时是否设置了SQLITE_OPEN_URI标志. 如果它是全局禁用的，则只有在打开数据库连接时设置了 SQLITE_OPEN_URI 标志时，文件名才会被解释为 URI。默认情况下，URI 处理是全局禁用的。默认值可以通过编译来改变 SQLITE_USE_URI符号定义。
- SQLITE_CONFIG_COVERING_INDEX_SCAN
- SQLITE_CONFIG_COVERING_INDEX_SCAN 选项采用单个整数参数，该参数被解释为布尔值，以便在查询优化器中启用或禁用覆盖索引以进行全表扫描。默认设置由SQLITE_ALLOW_COVERING_INDEX_SCAN编译时选项确定，或者如果省略该编译时选项则为“on”。禁用全表扫描覆盖索引的能力是因为一些错误编码的遗留应用程序在启用优化时可能会出现故障。提供禁用优化的能力允许旧的、有错误的应用程序代码无需更改即可工作，即使使用较新版本的 SQLite。
- SQLITE_CONFIG_PCACHE 和 SQLITE_CONFIG_GETPCACHE
- 这些选项已过时，不应由新代码使用。保留它们是为了向后兼容，但现在是空操作。
- SQLITE_CONFIG_SQLLOG
- 此选项仅在使用 SQLITE_ENABLE_SQLLOG编译 sqlite 时可用预处理器宏定义。第一个参数应该是指向类型为 void(*)(void*,sqlite3*,const char*, int) 的函数的指针。第二个应该是类型 (void*)。回调由库在三种不同的情况下调用，由作为第四个参数传递的值标识。如果第四个参数为0，那么作为第二个参数传递的数据库连接刚刚打开。第三个参数指向包含主数据库文件名称的缓冲区。如果第四个参数为1，那么第三个参数指向的SQL语句刚刚执行完毕。或者，如果第四个参数为 2，则作为第二个参数传递的连接将被关闭。第三个参数传给NULL，在这种情况下。在“test_sqllog.c”中可以看到使用此配置选项的示例
- SQLITE_CONFIG_MMAP_SIZE
- SQLITE_CONFIG_MMAP_SIZE 采用两个 64 位整数 (sqlite3_int64) 值，它们是默认的 mmap 大小限制（ PRAGMA mmap_size的默认设置）和允许的最大 mmap 大小限制。每个数据库连接都可以使用PRAGMA mmap_size命令或使用 SQLITE_FCNTL_MMAP_SIZE文件控制来覆盖默认设置。如有必要，允许的最大 mmap 大小将被静默截断，以使其不超过 SQLITE_MAX_MMAP_SIZE编译时选项设置的编译时最大 mmap 大小。如果此选项的任一参数为负，则该参数将更改为其编译时默认值。
- SQLITE_CONFIG_WIN32_HEAPSIZE
- SQLITE_CONFIG_WIN32_HEAPSIZE 选项仅在 SQLite 为 Windows 编译并定义了SQLITE_WIN32_MALLOC预处理器宏时才可用。SQLITE_CONFIG_WIN32_HEAPSIZE 采用 32 位无符号整数值，指定创建堆的最大大小。
- SQLITE_CONFIG_PCACHE_HDRSZ
- SQLITE_CONFIG_PCACHE_HDRSZ 选项采用单个参数，该参数是一个指向整数的指针，并将SQLITE_CONFIG_PAGECACHE中每一页所需的每页额外字节数写入该整数。所需的额外空间量可能因编译器、目标平台和 SQLite 版本而异。
- SQLITE_CONFIG_PMASZ
- SQLITE_CONFIG_PMASZ 选项采用一个无符号整数参数，并将多线程排序器的“最小 PMA 大小”设置为该整数。默认最小 PMA 大小由 SQLITE_SORTER_PMASZ编译时选项设置。当启用多线程排序（使用PRAGMA threads命令）并且要排序的内容量超过页面大小乘以 PRAGMA cache_size设置和此值的最小值时，将启动新线程以帮助进行排序操作。
- SQLITE_CONFIG_STMTJRNL_SPILL
- SQLITE_CONFIG_STMTJRNL_SPILL 选项采用单个参数，该参数成为语句日志溢出到磁盘的阈值。 语句日志保存在内存中，直到它们的大小（以字节为单位）超过此阈值，此时它们被写入磁盘。或者，如果阈值为 -1，则语句日志始终专门保存在内存中。由于许多语句日志永远不会变大，将溢出阈值设置为 64KiB 等值可以大大减少支持语句回滚所需的 I/O 量。此设置的默认值由 SQLITE_STMTJRNL_SPILL编译时选项控制。
- SQLITE_CONFIG_SORTERREF_SIZE
- SQLITE_CONFIG_SORTERREF_SIZE 选项接受类型为 (int) 的单个参数——排序器引用大小阈值的新值。通常，当 SQLite 使用外部排序根据 ORDER BY 子句对记录进行排序时，调用者需要的所有字段都存在于排序的记录中。但是，如果 SQLite 根据表列的声明类型确定它的值可能非常大——大于配置的排序器引用大小阈值——那么引用将存储在每个排序记录中，并从中加载所需的列值数据库作为记录按排序顺序返回。此选项的默认值是从不使用此优化。为此选项指定一个负值将恢复默认行为。此选项仅在使用 SQLite 编译时可用 SQLITE_ENABLE_SORTER_REFERENCES编译时选项。
- SQLITE_CONFIG_MEMDB_MAXSIZE
- SQLITE_CONFIG_MEMDB_MAXSIZE 选项接受单个参数 sqlite3_int64参数，这是使用sqlite3_deserialize()创建的内存数据库的默认最大大小。可以使用SQLITE_FCNTL_SIZE_LIMIT file-control为单个数据库向上或向下调整此默认最大大小 。如果从未使用过此配置设置，则默认最大值由SQLITE_MEMDB_DEFAULT_MAXSIZE编译时选项确定。如果未设置该编译时选项，则默认最大值为 1073741824。