Параметры конфигурации
#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
- Для этого параметра нет аргументов. Этот параметр устанавливает режим многопоточности режима потоков в Single-thread. Другими словами, он отключает все мьютексы и переводит SQLite в режим, в котором его может использовать только один поток. Если SQLite скомпилирован с параметром времени компиляции SQLITE_THREADSAFE=0, то изменить режим многопоточности режима потоков с его значения по умолчанию Single-thread невозможно, и поэтому sqlite3_config() вернет SQLITE_ERROR, если вызовется с конфигурационным параметром SQLITE_CONFIG_SINGLETHREAD.
- SQLITE_CONFIG_MULTITHREAD
- Для этого параметра нет аргументов. Этот параметр устанавливает режим многопоточности режима потоков в Multi-thread. Другими словами, он отключает мьютексы для объектов соединения с базой данных и подготовленных запросов. Приложение отвечает за сериализацию доступа к соединениям с базами данных и подготовленным запросам. Однако другие мьютексы включены, так что SQLite можно безопасно использовать в многопоточной среде, если ни два потока не пытаются использовать одно и то же соединение с базой данных одновременно. Если SQLite скомпилирован с параметром времени компиляции SQLITE_THREADSAFE=0, то установить режим многопоточности Multi-thread невозможно, и sqlite3_config() вернёт SQLITE_ERROR, если вызовется с конфигурационным параметром SQLITE_CONFIG_MULTITHREAD.
- SQLITE_CONFIG_SERIALIZED
- Для этого параметра нет аргументов. Этот параметр устанавливает режим многопоточности режима потоков в Serialized. Другими словами, этот параметр включает все мьютексы, включая рекурсивные мьютексы для объектов соединения с базой данных и подготовленных запросов. В этом режиме (который является значением по умолчанию, когда SQLite скомпилирован с SQLITE_THREADSAFE=1), библиотека SQLite сама сериализует доступ к соединениям с базами данных и подготовленным запросам, поэтому приложение может использовать одно и то же соединение с базой данных или один и тот же подготовленный запрос в разных потоках одновременно. Если 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 принимает один целочисленный аргумент, интерпретируемый как булево значение. Если оно истинно, это даёт SQLite подсказку, что следует избегать больших выделений памяти, если это возможно. SQLite будет работать быстрее, если ему разрешено выполнять большие выделения памяти, но некоторые приложения могут предпочесть работать медленнее в обмен на гарантии по фрагментации памяти, которая возможна, если избегать больших выделений. Эта подсказка обычно выключена.
- SQLITE_CONFIG_MEMSTATUS
- Параметр SQLITE_CONFIG_MEMSTATUS принимает один целочисленный аргумент, интерпретируемый как булево значение, которое включает или отключает сбор статистики выделения памяти. Когда статистика выделения памяти отключена, следующие интерфейсы 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 должен быть либо указателем NULL, либо указателем на выровненный по 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. SQLite создаёт копию содержимого структуры sqlite3_mutex_methods перед возвратом результата вызова sqlite3_config(). Если 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, а второй — количество слотов, выделенных для каждого соединения с базой данных. SQLITE_CONFIG_LOOKASIDE устанавливает значение по умолчанию для размера lookaside. Параметр SQLITE_DBCONFIG_LOOKASIDE функции sqlite3_db_config() может быть использован для изменения конфигурации 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 только если флаг 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. Возможность может быть включена только если SQLite скомпилирован с -DSQLITE_ALLOW_ROWID_IN_VIEW, в этом случае возможность включена по умолчанию. Эта опция конфигурации запрашивает текущую настройку или изменяет её на выключенную или включённую. Аргумент — указатель на целое число. Если это целое число изначально содержит значение 1, то возможность для представлений иметь ROWID активируется. Если целое число изначально содержит ноль, то возможность отключается. Любое другое начальное значение целого числа оставляет настройку без изменений. После изменений, если таковые есть, целое число записывается с 1 или 0, если возможность для представлений иметь ROWID включена или выключена. Если SQLite скомпилирован без -DSQLITE_ALLOW_ROWID_IN_VIEW (что является обычным и рекомендуемым случаем), то целое число всегда заполняется нулём, независимо от его начального значения.
См. также списки объектов, констант и функций.
SQLite is in the Public Domain.
https://sqlite.org/c3ref/c_config_covering_index_scan.html
