Параметры конфигурации
#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 */ #define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
Эти константы представляют собой доступные целочисленные параметры конфигурации, которые можно передать в качестве первого аргумента интерфейсу sqlite3_config().
Большинство параметров конфигурации для sqlite3_config() работают только в том случае, если вызваны до sqlite3_initialize() или после sqlite3_shutdown(). Немногочисленные исключения из этого правила называются «параметрами конфигурации, доступными в любое время». Вызов sqlite3_config() с первым аргументом, который не является параметром конфигурации, доступным в любое время, между вызовами sqlite3_initialize() и sqlite3_shutdown() ничего не делает и возвращает SQLITE_MISUSE.
Набор параметров конфигурации, доступных в любое время, может меняться (за счёт добавления и/или удаления параметров) от одного выпуска SQLite к следующему. В версии SQLite 3.42.0 полный набор параметров конфигурации, доступных в любое время, таков:
- SQLITE_CONFIG_LOG
- SQLITE_CONFIG_PCACHE_HDRSZ
В будущих выпусках SQLite могут появиться новые параметры конфигурации. Существующие параметры конфигурации могут быть упразднены. Приложениям следует проверять код возврата sqlite3_config(), чтобы убедиться, что вызов выполнен успешно. Интерфейс sqlite3_config() вернёт ненулевой код ошибки, если вызван упразднённый или неподдерживаемый параметр конфигурации.
- SQLITE_CONFIG_SINGLETHREAD
- У этого параметра нет аргументов. Он устанавливает режим многопоточности «Однопоточный». Иными словами, он отключает все мьютексы и переводит SQLite в режим, в котором библиотеку может использовать только один поток. Если SQLite скомпилирована с параметром компиляции SQLITE_THREADSAFE=0, изменить значение по умолчанию для режима многопоточности — «Однопоточный» — невозможно, поэтому sqlite3_config() вернёт SQLITE_ERROR, если вызвана с параметром конфигурации SQLITE_CONFIG_SINGLETHREAD.
- SQLITE_CONFIG_MULTITHREAD
- У этого параметра нет аргументов. Он устанавливает режим многопоточности «Многопоточный». Иными словами, он отключает мьютексы для объектов подключения к базе данных и подготовленных операторов. Приложение отвечает за сериализацию доступа к подключениям к базе данных и подготовленным операторам. При этом остальные мьютексы остаются включёнными, поэтому SQLite безопасно использовать в многопоточной среде, если только два потока не пытаются одновременно использовать одно и то же подключение к базе данных. Если SQLite скомпилирована с параметром компиляции SQLITE_THREADSAFE=0, установить режим многопоточности «Многопоточный» невозможно, и sqlite3_config() вернёт SQLITE_ERROR, если вызвана с параметром конфигурации SQLITE_CONFIG_MULTITHREAD.
- SQLITE_CONFIG_SERIALIZED
- У этого параметра нет аргументов. Он устанавливает режим многопоточности «Сериализованный». Иными словами, этот параметр включает все мьютексы, в том числе рекурсивные мьютексы для объектов подключения к базе данных и подготовленных операторов. В этом режиме (который используется по умолчанию, если SQLite скомпилирована с параметром SQLITE_THREADSAFE=1) библиотека SQLite сама сериализует доступ к подключениям к базе данных и подготовленным операторам, поэтому приложение может одновременно использовать одно и то же подключение к базе данных или один и тот же подготовленный оператор в разных потоках. Если SQLite скомпилирована с параметром компиляции SQLITE_THREADSAFE=0, установить режим многопоточности «Сериализованный» невозможно, и sqlite3_config() вернёт SQLITE_ERROR, если вызвана с параметром конфигурации SQLITE_CONFIG_SERIALIZED.
- 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, интерпретируемый как логическое значение. Если он равен true, то служит подсказкой SQLite по возможности избегать выделения больших блоков памяти. SQLite работает быстрее, если ей разрешено выделять большие блоки памяти, однако некоторые приложения могут предпочесть более низкую скорость в обмен на гарантии относительно фрагментации памяти, возможные при отказе от больших выделений. По умолчанию эта подсказка отключена.
- SQLITE_CONFIG_MEMSTATUS
- Параметр SQLITE_CONFIG_MEMSTATUS принимает один аргумент типа int, интерпретируемый как логическое значение, которое включает или отключает сбор статистики выделения памяти. Если статистика выделения памяти отключена, следующие интерфейсы SQLite перестают работать: По умолчанию статистика выделения памяти включена, если только SQLite не скомпилирована с параметром SQLITE_DEFAULT_MEMSTATUS=0; в этом случае статистика выделения памяти по умолчанию отключена.
- 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) плюс несколько дополнительных байтов для заголовка каждой страницы. Число дополнительных байтов, необходимых для заголовка страницы, можно определить с помощью SQLITE_CONFIG_PCACHE_HDRSZ. Если параметр sz больше необходимого, это безвредно, хотя и приводит к расходу лишней памяти. Аргумент pMem должен быть либо нулевым указателем, либо указателем на выровненный по 8 байтам блок памяти размером не менее sz*N байт; в противном случае дальнейшее поведение не определено. Если pMem не равен NULL, SQLite будет стараться использовать предоставленную память для нужд кэша страниц, переходя к sqlite3_malloc(), если строка кэша страниц больше sz байт или если весь буфер pMem исчерпан. Если pMem равен NULL, а N не равен нулю, каждое подключение к базе данных выполняет первоначальное массовое выделение памяти для кэша страниц с помощью 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. Аргумент задаёт альтернативные низкоуровневые процедуры работы с мьютексами, которые будут использоваться вместо встроенных в SQLite процедур работы с мьютексами. Перед возвратом из вызова sqlite3_config() SQLite копирует содержимое структуры sqlite3_mutex_methods. Если SQLite скомпилирована с параметром компиляции SQLITE_THREADSAFE=0, вся подсистема мьютексов исключается из сборки, поэтому вызовы sqlite3_config() с параметром конфигурации SQLITE_CONFIG_MUTEX возвращают SQLITE_ERROR.
- SQLITE_CONFIG_GETMUTEX
- Параметр SQLITE_CONFIG_GETMUTEX принимает один аргумент — указатель на экземпляр структуры sqlite3_mutex_methods. Структура sqlite3_mutex_methods заполняется текущими процедурами работы с мьютексами. Этот параметр можно использовать, например, чтобы заменить стандартные процедуры выделения мьютексов обёрткой для отслеживания использования мьютексов при профилировании производительности или тестировании. Если SQLite скомпилирована с параметром компиляции SQLITE_THREADSAFE=0, вся подсистема мьютексов исключается из сборки, поэтому вызовы sqlite3_config() с параметром конфигурации SQLITE_CONFIG_GETMUTEX возвращают SQLITE_ERROR.
- SQLITE_CONFIG_LOOKASIDE
- Параметр SQLITE_CONFIG_LOOKASIDE принимает два аргумента, определяющих размер буфера lookaside по умолчанию для каждого подключения к базе данных. Первый аргумент — размер каждого слота буфера lookaside («sz»), а второй — количество слотов, выделяемых для каждого подключения к базе данных («cnt»). SQLITE_CONFIG_LOOKASIDE задаёт размер lookaside по умолчанию. Параметр SQLITE_DBCONFIG_LOOKASIDE интерфейса sqlite3_db_config() можно использовать для изменения конфигурации lookaside отдельных подключений. Параметр -DSQLITE_DEFAULT_LOOKASIDE можно использовать для изменения конфигурации 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() ничего не делает. Указатель на void, являющийся вторым аргументом 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 при открытии подключения к базе данных. Если обработка URI глобально отключена, имена файлов интерпретируются как URI, только если при открытии подключения к базе данных установлен флаг SQLITE_OPEN_URI. По умолчанию обработка URI глобально отключена. Значение по умолчанию можно изменить, определив символ SQLITE_USE_URI при компиляции.
- SQLITE_CONFIG_COVERING_INDEX_SCAN
- Параметр SQLITE_CONFIG_COVERING_INDEX_SCAN принимает один целочисленный аргумент, который интерпретируется как логическое значение и включает или отключает использование покрывающих индексов для полного сканирования таблиц в оптимизаторе запросов. Значение по умолчанию определяется параметром компиляции SQLITE_ALLOW_COVERING_INDEX_SCAN или, если этот параметр компиляции не указан, равно «включено». Возможность отключить использование покрывающих индексов при полном сканировании таблиц предусмотрена потому, что некоторые некорректно написанные устаревшие приложения могут работать неправильно при включённой оптимизации. Возможность отключить оптимизацию позволяет старому ошибочному коду приложения работать без изменений даже с новыми версиями SQLite.
- SQLITE_CONFIG_PCACHE and 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 принимает один параметр — беззнаковое целое число — и задаёт этим числом «минимальный размер PMA» для многопоточной сортировки. Минимальный размер PMA по умолчанию задаётся параметром компиляции SQLITE_SORTER_PMASZ. При включённой многопоточной сортировке (с помощью команды PRAGMA threads) запускаются дополнительные потоки для выполнения сортировки, если объём сортируемых данных превышает размер страницы, умноженный на меньшее из значений PRAGMA cache_size и этого параметра.
- SQLITE_CONFIG_STMTJRNL_SPILL
- Параметр SQLITE_CONFIG_STMTJRNL_SPILL принимает один параметр, который задаёт порог сброса журнала операторов на диск. Журналы операторов хранятся в памяти, пока их размер в байтах не превысит этот порог; после этого они записываются на диск. Если порог равен -1, журналы операторов всегда хранятся исключительно в памяти. Поскольку многие журналы операторов никогда не становятся большими, установка порога сброса, например, в 64 КиБ может значительно сократить объём ввода-вывода, необходимый для поддержки отката операторов. Значение этого параметра по умолчанию контролируется параметром компиляции 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. Если этот параметр конфигурации ни разу не использовался, максимальный размер по умолчанию определяется параметром компиляции SQLITE_MEMDB_DEFAULT_MAXSIZE. Если этот параметр компиляции не задан, максимальный размер по умолчанию равен 1073741824.
- SQLITE_CONFIG_ROWID_IN_VIEW
- Параметр SQLITE_CONFIG_ROWID_IN_VIEW включает или отключает возможность наличия ROWID у VIEW. Эту возможность можно включить только в том случае, если SQLite скомпилирована с -DSQLITE_ALLOW_ROWID_IN_VIEW; в этом случае по умолчанию она включена. Этот параметр конфигурации позволяет запросить текущее значение или изменить его на «выключено» либо «включено». Аргументом служит указатель на целое число. Если изначально это целое число содержит значение 1, возможность наличия ROWID у VIEW включается. Если изначально целое число содержит ноль, эта возможность отключается. При любом другом исходном значении целого числа параметр остаётся без изменений. После внесения изменений, если они были, в целое число записывается 1 или 0 в зависимости от того, включена или отключена возможность наличия ROWID у VIEW. Если SQLite скомпилирована без -DSQLITE_ALLOW_ROWID_IN_VIEW (что обычно и рекомендуется), в целое число всегда записывается ноль независимо от его исходного значения.
См. также списки объектов, констант и функций.
SQLite is in the Public Domain.
https://sqlite.org/c3ref/c_config_covering_index_scan.html
