Настройки конфигурации подключения к базе данных

#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_STMT_SCANSTATUS       1018 /* int int* */
#define SQLITE_DBCONFIG_REVERSE_SCANORDER     1019 /* int int* */
#define SQLITE_DBCONFIG_MAX                   1019 /* Largest DBCONFIG */

Эти константы — доступные целочисленные параметры конфигурации, которые можно передать в качестве второго аргумента интерфейсу sqlite3_db_config().

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

SQLITE_DBCONFIG_LOOKASIDE

Этот параметр принимает три дополнительных аргумента, которые определяют конфигурацию аллокатора памяти lookaside для соединения с базой данных. Первый аргумент (третий параметр функции sqlite3_db_config()) — указатель на буфер памяти, который будет использоваться для lookaside памяти. Первый аргумент после команды SQLITE_DBCONFIG_LOOKASIDE может быть NULL, в этом случае SQLite выделит буфер lookaside сам, используя sqlite3_malloc(). Второй аргумент — размер каждого слота буфера lookaside. Третий аргумент — количество слотов. Размер буфера в первом аргументе должен быть больше или равен произведению второго и третьего аргументов. Буфер должен быть выровнен на границе 8 байт. Если второй аргумент SQLITE_DBCONFIG_LOOKASIDE не кратен 8, он внутренне округляется вниз до ближайшего меньшего кратного 8. Конфигурация памяти lookaside для соединения с базой данных может быть изменена только тогда, когда это соединение не использует память lookaside, или, другими словами, когда «текущее значение», возвращаемое функцией sqlite3_db_status(D,SQLITE_DBSTATUS_LOOKASIDE_USED,...), равно нулю. Любая попытка изменить конфигурацию памяти lookaside, когда память lookaside используется, оставляет конфигурацию неизменной и возвращает SQLITE_BUSY.

SQLITE_DBCONFIG_ENABLE_FKEY

Этот параметр используется для включения или отключения принудительного выполнения ограничений внешнего ключа. Должны быть два дополнительных аргумента. Первый аргумент — целое число, которое равно 0 для отключения принудительного выполнения ограничений внешнего ключа, положительному значению для включения принудительного выполнения или отрицательному значению для оставления принудительного выполнения неизменным. Второй параметр — указатель на целое число, в которое записывается 0 или 1, чтобы указать, отключено или включено принудительное выполнение ограничений внешнего ключа после этого вызова. Второй параметр может быть указателем NULL, в этом случае настройка принудительного выполнения ограничений внешнего ключа не будет сообщена обратно.

SQLITE_DBCONFIG_ENABLE_TRIGGER

Этот параметр используется для включения или отключения триггеров. Должны быть два дополнительных аргумента. Первый аргумент — целое число, которое равно 0 для отключения триггеров, положительному значению для включения триггеров или отрицательному значению для оставления настройки неизменной. Второй параметр — указатель на целое число, в которое записывается 0 или 1, чтобы указать, отключены или включены триггеры после этого вызова. Второй параметр может быть указателем NULL, в этом случае настройка триггеров не будет сообщена обратно.

Изначально этот параметр отключал все триггеры. Однако, начиная с версии SQLite 3.35.0, временные триггеры все еще разрешены, даже если этот параметр выключен. Иными словами, этот параметр теперь отключает триггеры только в основной схеме базы данных или в схемах присоединенных баз данных.

SQLITE_DBCONFIG_ENABLE_VIEW

Этот параметр используется для включения или отключения видов. Должны быть два дополнительных аргумента. Первый аргумент — целое число, которое равно 0 для отключения видов, положительному значению для включения видов или отрицательному значению для оставления настройки неизменной. Второй параметр — указатель на целое число, в которое записывается 0 или 1, чтобы указать, отключены или включены виды после этого вызова. Второй параметр может быть указателем NULL, в этом случае настройка видов не будет сообщена обратно.

Изначально этот параметр отключал все виды. Однако, начиная с версии SQLite 3.35.0, временные виды все еще разрешены, даже если этот параметр выключен. Иными словами, этот параметр теперь отключает виды только в основной схеме базы данных или в схемах присоединенных баз данных.

SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

Этот параметр используется для включения или отключения функции fts3_tokenizer(), которая является частью расширения полнотекстового поиска FTS3. Должны быть два дополнительных аргумента. Первый аргумент — целое число, которое равно 0 для отключения fts3_tokenizer(), положительному значению для включения fts3_tokenizer() или отрицательному значению для оставления настройки неизменной. Второй параметр — указатель на целое число, в которое записывается 0 или 1, чтобы указать, отключена или включена функция fts3_tokenizer() после этого вызова. Второй параметр может быть указателем NULL, в этом случае новая настройка не будет сообщена обратно.

SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

Этот параметр используется для включения или отключения интерфейса sqlite3_load_extension() независимо от SQL-функции load_extension(). API sqlite3_enable_load_extension() включает или отключает как 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, "VACUUM", 0, 0, 0);
sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);

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

SQLITE_DBCONFIG_DEFENSIVE

Параметр SQLITE_DBCONFIG_DEFENSIVE активирует или деактивирует «оборонительный» флаг для соединения с базой данных. Когда флаг «оборонительный» включен, функции языка, которые позволяют обычным SQL-командам преднамеренно повредить файл базы данных, отключаются. К отключенным функциям относятся, но не ограничиваются ими:

Команда PRAGMA writable_schema=ON.
Команда PRAGMA journal_mode=OFF.
Команда PRAGMA schema_version=N.
Записи в виртуальную таблицу 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 принимает дополнительные меры защиты приложения от вредоносного кода, включая:

Запрет использования функций SQL внутри триггеров, представлений, ограничений CHECK, предложений DEFAULT, индексов выражений, частичных индексов или сгенерированных столбцов, если эти функции не помечены как SQLITE_INNOCUOUS.
Запрет использования виртуальных таблиц внутри триггеров или представлений, если эти виртуальные таблицы не помечены как SQLITE_VTAB_INNOCUOUS.

По умолчанию эта настройка включена для совместимости со старыми версиями, однако всем приложениям рекомендуется выключать её, если это возможно. Данную настройку также можно контролировать с помощью оператора PRAGMA trusted_schema.

SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

Параметр SQLITE_DBCONFIG_LEGACY_FILE_FORMAT включает или отключает флаг устаревшего формата файла. При включении этого флага все вновь созданные файлы баз данных будут иметь номер версии схемы (4-байтовое целое число, найденное по смещению 44 в заголовке базы данных) равный 1. Это, в свою очередь, означает, что получившийся файл базы данных будет читаться и записываться любой версией SQLite до 3.0.0 (2004-06-18). Без этой настройки вновь созданные базы данных обычно не будут понятны версиям SQLite, предшествующим 3.3.0 (2006-01-11). На данный момент вряд ли есть необходимость создавать файлы баз данных, совместимые со всеми версиями вплоть до 3.0.0, поэтому эта настройка практически бесполезна, но она присутствует для того, чтобы SQLite продолжала поддерживать возможность создания новых файлов баз данных, совместимых с версией 3.0.0.

Обратите внимание, что при включенном SQLITE_DBCONFIG_LEGACY_FILE_FORMAT, команда VACUUM завершится с неясным сообщением об ошибке при попытке обработки таблицы с сгенерированными столбцами и индексом с убыванием. Это не считается ошибкой, так как версии SQLite 3.3.0 и более ранние не поддерживают ни сгенерированные столбцы, ни индексы с убыванием.

SQLITE_DBCONFIG_STMT_SCANSTATUS

Параметр SQLITE_DBCONFIG_STMT_SCANSTATUS полезен только в сборках SQLITE_ENABLE_STMT_SCANSTATUS. В этом случае он устанавливает или сбрасывает флаг, который включает сбор статистики sqlite3_stmt_scanstatus_v2(). Для сбора статистики флаг должен быть установлен в обработчике базы данных как при подготовке SQL-запроса, так и при его выполнении. Флаг установлен (сбор статистики включен) по умолчанию. Этот параметр принимает два аргумента: целое число и указатель на целое число. Первый аргумент — 1, 0 или -1 для включения, отключения или сохранения без изменений параметра statement scanstatus. Если второй аргумент не NULL, то значение параметра statement scanstatus после обработки первого аргумента записывается в целое число, на которое указывает второй аргумент.

SQLITE_DBCONFIG_REVERSE_SCANORDER

Параметр SQLITE_DBCONFIG_REVERSE_SCANORDER изменяет порядок по умолчанию, в котором сканируются таблицы и индексы, так что сканирование начинается с конца и идёт к началу, а не с начала и идёт к концу. Установка SQLITE_DBCONFIG_REVERSE_SCANORDER эквивалентна установке PRAGMA reverse_unordered_selects. Этот параметр принимает два аргумента — целое число и указатель на целое число. Первый аргумент — 1, 0 или -1, чтобы включить, отключить или оставить без изменений флаг обратного порядка сканирования соответственно. Если второй аргумент не равен NULL, то в целое число, на которое указывает второй аргумент, записывается 0 или 1 в зависимости от того, установлен ли флаг обратного порядка сканирования после обработки первого аргумента.

См. также списки объектов, констант и функций.

SQLite is in the Public Domain.
https://sqlite.org/c3ref/c_dbconfig_defensive.html