Параметры конфигурации

#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().

Большинство параметров конфигурации для sqlite3_config() будет работать только, если вызваны до sqlite3_initialize() или после sqlite3_shutdown(). Несколько исключений из этого правила называют "параметры конфигурации в любое время". Вызов sqlite3_config() с первым аргументом, который не является параметром конфигурации в любое время, который промежуточно вызывает sqlite3_initialize() и sqlite3_shutdown() , не делает ничего и возвращает SQLITE_MISUSE.

Набор параметров конфигурации в любое время может измениться (вставками и/или удалениями) от одного выпуска SQLite к следующему. С версии SQLite version 3.42.0 полный набор параметров конфигурации в любое время:

• SQLITE_CONFIG_LOG
• SQLITE_CONFIG_PCACHE_HDRSZ

Новые параметры конфигурации могут быть добавлены в будущих выпусках SQLite. Могли бы быть прекращены существующие параметры конфигурации. Запросы должны проверить код возврата от sqlite3_config(), чтобы удостовериться, что запрос работал. sqlite3_config() возвратит ненулевой код ошибки, если прекращенный или неподдержанный параметр конфигурации будет вызван.

SQLITE_CONFIG_SINGLETHREAD

Нет никаких аргументов. Этот выбор устанавливает многопоточный режим в Single-thread. Другими словами, это отключает весь mutexing и помещает SQLite в режим, где это может использоваться только единственным потоком. Если SQLite собран с выбором времени компиляции SQLITE_THREADSAFE=0, невозможно изменить многопоточный режим от значения по умолчанию Single-thread, таким образом sqlite3_config() вернет SQLITE_ERROR, если вызван с параметром конфигурации SQLITE_CONFIG_SINGLETHREAD.

SQLITE_CONFIG_MULTITHREAD

Этот выбор устанавливает многопоточный режим в Multi-thread. Другими словами, это отключает mutexing на объектах соединении с базой данных и подготовленных запросах. Приложение ответственно за преобразование в последовательную форму доступа к ним. Но другие mutexes позволены так, чтобы SQLite было безопасно использовать в многопоточной окружающей среде, пока никакие два потока не пытаются использовать то же самое соединение с базой данных в то же время. Если SQLite собран с выбором времени компиляции SQLITE_THREADSAFE=0, невозможно установить многопоточный режим в Multi-thread и sqlite3_config() вернет SQLITE_ERROR, если вызван с параметром конфигурации SQLITE_CONFIG_MULTITHREAD.

SQLITE_CONFIG_SERIALIZED

Этот выбор устанавливает многопоточный режим в Serialized. Другими словами, этот выбор позволяет все mutexes, включая рекурсивные mutexes на соединении с базой данных и подготовленных запросах. В этом режиме (который является умолчанием, когда SQLite собран с SQLITE_THREADSAFE=1) библиотека SQLite самостоятельно преобразует в последовательную форму доступ к соединениям с базой данных и подготовленным запросам так, чтобы применение могло использовать то же самое соединение с базой данных или same подготовленный запрос в различных потоках в то же время. Если SQLite собран с выбором времени компиляции SQLITE_THREADSAFE=0, невозможно установить многопоточный режим в Serialized и sqlite3_config() вернет SQLITE_ERROR, если вызван с параметром конфигурации SQLITE_CONFIG_SERIALIZED.

SQLITE_CONFIG_MALLOC

SQLITE_CONFIG_MALLOC берет отдельный аргумент, который является указателем на экземпляр структуры sqlite3_mem_methods. Аргумент определяет альтернативные режимы выделения памяти низкого уровня, которые будут использоваться вместо режимов выделения памяти, встроенных в SQLite. SQLite делает свою собственную частную копию содержания структуры sqlite3_mem_methods перед вызовом sqlite3_config().

SQLITE_CONFIG_GETMALLOC

Опция SQLITE_CONFIG_GETMALLOC берет отдельный аргумент, который является указателем на экземпляр структуры sqlite3_mem_methods. sqlite3_mem_methods заполнена в настоящее время определяемыми режимами выделения памяти. Этот выбор может использоваться, чтобы перегрузить режимы выделения памяти по умолчанию оберткой, например, для моделирований или отслеживания использования памяти.

SQLITE_CONFIG_SMALL_MALLOC

Опция SQLITE_CONFIG_SMALL_MALLOC берет отдельный аргумент типа int, интерпретируемый как boolean, который, если true предоставляет намек SQLite, что это должно избежать выделения памяти большой емкости, если это возможно. SQLite будет работать быстрее, если это будет свободно сделать выделения памяти большой емкости, но некоторое применение могло бы предпочесть работать медленнее в обмен на гарантии отсутствия фрагментации памяти, которые возможны, если больших выделений избегают. Этот намек обычно выключен.

SQLITE_CONFIG_MEMSTATUS

SQLITE_CONFIG_MEMSTATUS берет отдельный аргумент типа int, интерпретируемый как boolean, который, позволяет или отключает сбор статистики выделения памяти. Когда статистические данные выделения памяти отключены, следующие интерфейсы SQLite становятся не влияющими на эксплуатацию:

• sqlite3_hard_heap_limit64()
• sqlite3_memory_used()
• sqlite3_memory_highwater()
• sqlite3_soft_heap_limit64()
• sqlite3_status64()

Статистические данные выделения памяти позволены по умолчанию, если SQLite не собран с SQLITE_DEFAULT_MEMSTATUS =0, в этом случае, статистические данные выделения памяти отключены по умолчанию.

SQLITE_CONFIG_SCRATCH

Больше не используется.

SQLITE_CONFIG_PAGECACHE

SQLITE_CONFIG_PAGECACHE определяет пул памяти, который SQLite может использовать для кэша страницы базы данных с внедрением кэша страницы по умолчанию. Этот параметр конфигурации не работает, если определенное применением внедрение кэша страницы загружается, используя SQLITE_CONFIG_PCACHE2. Есть три аргумента SQLITE_CONFIG_PAGECACHE: указатель на 8 байтно выровненную память (pMem), размер каждой страницы кэша строки (sz) и количество строк кэша (N). sz должен быть размером самой большой страницы базы данных (степень двойки между 512 и 65536) плюс некоторые дополнительные байты для каждого заголовка страницы. Число дополнительных байтов, необходимых заголовку страницы, может быть определено, используя SQLITE_CONFIG_PCACHE_HDRSZ. Это безопасно, кроме потраченной впустую памяти, для параметра sz, если он больше, чем необходимо. pMem должен быть NULL или указателем на выровненный по 8 байтов блок памяти хотя бы sz*N байт, в других отношениях последующее поведение не определено. Когда pMem не NULL, SQLite будет стремиться использовать память, обеспеченную, чтобы удовлетворить потребности кэша страницы, отступая к sqlite3_malloc(), если строка кэша страницы будет больше, чем sz байт или весь буфер pMem исчерпан. Если pMem = NULL и N не 0, то каждое соединение с базой данных делает начальное оптовое отчисление на кэш-память страницы от sqlite3_malloc() достаточное для N строк кэша, если N положительный или -1024*N байт, если N отрицателен. Если дополнительная кэш-память страницы необходима вне того, что обеспечивается начальным распределением, то SQLite использует sqlite3_malloc() отдельно для каждой дополнительной строки кэша.

SQLITE_CONFIG_HEAP

SQLITE_CONFIG_HEAP определяет буфер статической памяти, который SQLite будет использовать для всех его потребностей динамического выделения памяти вне предусмотренных SQLITE_CONFIG_PAGECACHE. SQLITE_CONFIG_HEAP доступен только если SQLite собран с SQLITE_ENABLE_MEMSYS3 или SQLITE_ENABLE_MEMSYS5 и возвращает 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 . Аргумент определяет альтернативный mutex низкого уровня, который будет использоваться вместо mutex, встроенного в SQLite. SQLite делает копию содержания структуры sqlite3_mutex_methods перед запросом к sqlite3_config(). Если SQLite собран с выбором времени компиляции SQLITE_THREADSAFE=0, тогда, вся mutexing подсистема пропущена и следовательно вызов sqlite3_config() с SQLITE_CONFIG_MUTEX вернет SQLITE_ERROR.

SQLITE_CONFIG_GETMUTEX

SQLITE_CONFIG_GETMUTEX берет отдельный аргумент, который является указателем на экземпляр структуры sqlite3_mutex_methods. sqlite3_mutex_methods заполнена в настоящее время определяемым mutex. Этот выбор может использоваться, чтобы перегрузить умолчание подпрограммы распределения mutex оберткой, используемой, например, чтобы отследить использование mutex для исполнительного профилирования или тестирования. Если SQLite собран с выбором времени компиляции SQLITE_THREADSAFE=0, вся подсистема mutexing опущена и следовательно вызов sqlite3_config() с SQLITE_CONFIG_GETMUTEX вернет SQLITE_ERROR.

SQLITE_CONFIG_LOOKASIDE

SQLITE_CONFIG_LOOKASIDE берет два аргумента, которые определяют размер по умолчанию сохраняющей памяти на каждом соединении с базой данных. Первый аргумент это размер каждого места буфера предыстории, вторым является количество мест, ассигнованных каждому соединению с базой данных. SQLITE_CONFIG_LOOKASIDE задает размер хранения по умолчанию. Опция SQLITE_DBCONFIG_LOOKASIDE для sqlite3_db_config() может использоваться, чтобы изменить сохраняющую конфигурацию на отдельных связях.

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_CONFIG_LOG берет два аргумента: указатель на функцию с сигнатурой вызова void(*)(void*,int,const char*) и указатель на void. Если указатель функции не NULL, она вызвана sqlite3_log(), чтобы обработать каждое событие регистрации. Если указатель функции NULL, sqlite3_log() ничего не делает. Через указатель void, который является вторым аргументом SQLITE_CONFIG_LOG, передают первый параметр к определенной применением функции журналирования каждый раз, когда та функция вызвана. Второй параметр функции журналирования это копия первого параметра соответствующего вызова sqlite3_log(), предназначается, чтобы быть кодом результата или расширенным кодом результата. Третий параметр, переданный функции журналирования, является сообщением регистрации после форматирования через sqlite3_snprintf(). Функция журналирования, поставляемая применением, не должна вызывать интерфейс SQLite. В многопоточном применении определенная применением функция должна быть ориентирована на многопоточное исполнение.

SQLITE_CONFIG_URI

SQLITE_CONFIG_URI берет отдельный аргумент int. Если отличный от нуля, то обработка URI глобально позволена. Если параметр ноль, то обработка URI глобально отключена. Если обработка URI глобально позволена, все имена файлов, переданные sqlite3_open(), sqlite3_open_v2(), sqlite3_open16() или указанные как часть команд ATTACH, интерпретируются как URI, независимо от того, установлен ли флаг SQLITE_OPEN_URI, когда соединение с базой данных открыто. Если это глобально отключено, имена файлов интерпретируются как URI только, если флаг SQLITE_OPEN_URI установлен, когда соединение с базой данных открыто. По умолчанию обработка URI глобально отключена. Значение по умолчанию может быть изменено, собрав с определенным символом SQLITE_USE_URI.

SQLITE_CONFIG_COVERING_INDEX_SCAN

SQLITE_CONFIG_COVERING_INDEX_SCAN берет единичный целочисленный аргумент, который интерпретируется как boolean, чтобы позволить или отключить использование покрытия индексов для полного сканирования таблицы в оптимизаторе запросов. Настройка по умолчанию определяется выбором времени компиляции SQLITE_ALLOW_COVERING_INDEX_SCAN или "on", если тот выбор времени компиляции опущен. Возможность отключить использование покрытия индексов для полного сканирования таблицы состоит в том, потому что некоторые неправильные унаследованные приложения могли бы работать со сбоями, когда оптимизация позволена. Обеспечение возможности отключить оптимизацию позволяет более старому коду работать без изменения даже с более новыми версиями SQLite.

SQLITE_CONFIG_PCACHE и SQLITE_CONFIG_GETPCACHE

Эти опции устаревшие и не должны использоваться новым кодом. Они сохраняются для совместимости.

SQLITE_CONFIG_SQLLOG

Этот выбор доступен только если sqlite собран с определенным макросом препроцессора SQLITE_ENABLE_SQLLOG. Первый аргумент должен быть указателем на функцию типа void(*)(void*,sqlite3*,const char*, int). Второй должно иметь тип (void*). Отзыв вызван библиотекой при трех отдельных обстоятельствах, определенных значением, переданным как четвертый параметр. Если четвертый параметр 0, то соединение с базой данных, переданное как второй аргумент, было открыто. Третий аргумент указывает на буфер, содержащий название главного файла базы данных. Если четвертый параметр равняется 1, то SQL-оператор, на который указывает третий параметр, был выполнен. Или, если четвертый параметр равняется 2, то связь, передаваемая как второй параметр, закрывается. Третий параметр в этом случае NULL. Пример использования этого параметра конфигурации может быть замечен в файле "test_sqllog.c" в каноническом исходном дереве SQLite.

SQLITE_CONFIG_MMAP_SIZE

SQLITE_CONFIG_MMAP_SIZE берет два 64-битных целых (sqlite3_int64) значения, которые являются умолчанием предела размера mmap (настройка по умолчанию для PRAGMA mmap_size) и максимум позволенного mmap предела размера. Настройка по умолчанию может быть отвергнута каждым соединением с базой данных, используя PRAGMA mmap_size или через SQLITE_FCNTL_MMAP_SIZE. Позволенный mmap размер максимума будет тихо усечен, если надо, чтобы он не превышал максимум размера mmap времени компиляции, установленный выбором времени компиляции SQLITE_MAX_MMAP_SIZE. Если любой аргумент этой опции отрицателен, то тот аргумент изменяется на его умолчание времени компиляции.

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 берет единственный параметр, который является целым без знака и устанавливает "Minimum PMA Size" для многопоточного сортировщика к этому целому числу. Минимум по умолчанию PMA Size устанавливается выбором времени компиляции 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.