Операторы PRAGMA

Оператор PRAGMA — это расширение SQL, специфичное для SQLite и используемое для изменения работы библиотеки SQLite или для получения из библиотеки SQLite внутренних данных (не относящихся к таблицам). Оператор PRAGMA задаётся с использованием того же интерфейса, что и другие команды SQLite (например, SELECT, INSERT), но отличается следующими важными особенностями:

• Команда PRAGMA специфична для SQLite и несовместима с другими системами управления базами данных SQL.
• В будущих выпусках SQLite некоторые операторы PRAGMA могут быть удалены, а другие добавлены. Обратная совместимость не гарантируется.
• Если указан неизвестный оператор PRAGMA, сообщения об ошибке не генерируются. Неизвестные операторы PRAGMA просто игнорируются. Это означает, что если в операторе PRAGMA допущена опечатка, библиотека не уведомит об этом пользователя.
• Некоторые операторы PRAGMA вступают в силу на этапе компиляции SQL, а не на этапе выполнения. Это означает, что при использовании API языка C sqlite3_prepare(), sqlite3_step(), sqlite3_finalize() (или аналогичного интерфейса-обёртки) оператор PRAGMA может выполняться во время вызова sqlite3_prepare(), а не во время вызова sqlite3_step(), как это обычно происходит с операторами SQL. Либо оператор PRAGMA может выполняться во время sqlite3_step(), как и обычные операторы SQL. Выполняется ли оператор PRAGMA во время sqlite3_prepare() или sqlite3_step(), зависит от самого оператора PRAGMA и конкретного выпуска SQLite.
• Префиксы EXPLAIN и EXPLAIN QUERY PLAN для операторов SQL влияют только на поведение оператора во время sqlite3_step(). Это означает, что операторы PRAGMA, вступающие в силу во время sqlite3_prepare(), будут вести себя одинаково независимо от того, предварены ли они словом "EXPLAIN".

API SQLite на языке C предоставляет средство SQLITE_FCNTL_PRAGMA для управления файлами, которое даёт реализациям VFS возможность добавлять новые операторы PRAGMA или переопределять значение встроенных операторов PRAGMA.

Синтаксис команды PRAGMA

pragma-stmt: скрыть

Директива PRAGMA может принимать ноль или один аргумент. Аргумент может быть заключён в скобки или отделён от имени директивы знаком равенства. Оба синтаксиса дают одинаковые результаты. Во многих директивах аргумент является логическим значением. Логическое значение может быть одним из следующих:

Аргументы-ключевые слова можно заключать в кавычки. (Пример: 'yes' [FALSE].) Некоторые директивы принимают в качестве аргумента строковый литерал. Если директива принимает аргумент-ключевое слово, обычно ей также можно передать эквивалентное числовое значение. Например, «0» и «no» означают одно и то же, как и «1» и «yes». При запросе значения настройки многие директивы возвращают число, а не ключевое слово.

Перед именем директивы PRAGMA может указываться необязательное имя schema-name. schema-name — это имя базы данных, присоединённой с помощью ATTACH, либо "main" или "temp" для основных баз данных и TEMP. Если необязательное имя схемы не указано, предполагается "main". В некоторых директивах имя схемы не имеет значения и просто игнорируется. В приведённой ниже документации директивы PRAGMA, для которых имя схемы имеет значение, показаны с префиксом "schema.".

Функции PRAGMA

Директивы PRAGMA, которые возвращают результаты и не имеют побочных эффектов, доступны в обычных операторах SELECT в виде табличных функций. Для каждой такой директивы PRAGMA соответствующая табличная функция имеет то же имя, что и PRAGMA, с добавленным в начало семисимвольным префиксом "pragma_". Аргументы PRAGMA и имя схемы, если они есть, передаются табличной функции в качестве аргументов; имя схемы является необязательным последним аргументом.

Например, сведения о столбцах индекса можно получить с помощью директивы index_info следующим образом:

PRAGMA index_info('idx52');

Или то же содержимое можно получить с помощью:

SELECT * FROM pragma_index_info('idx52');

Преимущество формата табличной функции состоит в том, что запрос может возвращать только подмножество столбцов PRAGMA, содержать предложение WHERE, использовать агрегатные функции, а табличная функция может быть одним из нескольких источников данных в соединении. Например, чтобы получить список всех индексированных столбцов в схеме, можно выполнить запрос:

SELECT DISTINCT m.name || '.' || ii.name AS 'indexed-columns'
  FROM sqlite_schema AS m,
       pragma_index_list(m.name) AS il,
       pragma_index_info(il.name) AS ii
 WHERE m.type='table'
 ORDER BY 1;

Дополнительные примечания:

• Табличные функции существуют только для встроенных PRAGMA, но не для PRAGMA, определённых с помощью файлового управляющего вызова SQLITE_FCNTL_PRAGMA.

• Табличные функции существуют только для PRAGMA, которые возвращают результаты и не имеют побочных эффектов.

• Эту возможность можно использовать для реализации информационной схемы: сначала создайте отдельную схему с помощью

  ATTACH ':memory:' AS 'information_schema';
  

  Затем создайте в этой схеме представления (VIEW), реализующие официальные таблицы информационной схемы с помощью табличных функций PRAGMA.

• Табличные функции для PRAGMA появились в SQLite версии 3.16.0 (2017-01-02). В более ранних версиях SQLite эту возможность использовать нельзя.

Список PRAGMA

Примечания:

1. Устаревшими являются PRAGMA, названия которых зачёркнуты. Не используйте их. Они сохранены для обратной совместимости.
2. Эти PRAGMA доступны только в сборках, созданных с нестандартными параметрами компиляции.
3. Эти PRAGMA используются для тестирования SQLite и не рекомендуются к использованию в приложениях.

PRAGMA analysis_limit;
PRAGMA analysis_limit = N;

Запрашивает или изменяет ограничение для параметра приближённого ANALYZE. Оно задаёт приблизительное количество строк, проверяемых в каждом индексе командой ANALYZE. Если аргумент N опущен, ограничение анализа не изменяется. Если ограничение равно нулю, анализ не ограничен, и команда ANALYZE проверит все строки каждого индекса. Если N больше нуля, ограничение анализа устанавливается в N, и последующие команды ANALYZE прекратят анализ каждого индекса после проверки приблизительно N строк. Если N — отрицательное число или значение не является целым числом, PRAGMA ведёт себя так, как если бы аргумент N был опущен. Во всех случаях возвращается новое ограничение анализа, которое будет использоваться в последующих командах ANALYZE.

Эту PRAGMA можно использовать, чтобы ускорить выполнение команды ANALYZE для больших баз данных. Результаты анализа будут менее точными, если проверена только часть каждого индекса, но обычно их точности достаточно. Если задать N равным 100 или 1000, команда ANALYZE будет выполняться быстро даже для баз данных огромного размера.

Эта PRAGMA появилась в SQLite версии 3.32.0 (2020-05-22). Текущая реализация использует только младшие 31 бит значения N — старшие биты без предупреждения игнорируются. В будущих версиях SQLite могут начать использоваться и старшие биты.

Начиная с SQLite версии 3.46.0 (2024-05-23), рекомендуемый способ запуска ANALYZE — команда PRAGMA optimize. Команда PRAGMA optimize автоматически задаёт разумный временный предел анализа, благодаря которому команда PRAGMA optimize завершается быстро даже на огромных базах данных. Приложения, использующие PRAGMA optimize вместо непосредственного запуска ANALYZE, не должны задавать предел анализа.

PRAGMA schema.application_id;
PRAGMA schema.application_id = integer ;

PRAGMA application_id используется для запроса или задания 32-разрядного знакового целого числа в порядке байтов от старшего к младшему — «идентификатора приложения», расположенного по смещению 68 в заголовке базы данных. Приложения, использующие SQLite в качестве формата файлов приложения, должны задавать для идентификатора приложения уникальное целое число, чтобы такие утилиты, как file(1), могли определить конкретный тип файла, а не просто сообщать «База данных SQLite3». Список назначенных идентификаторов приложений можно найти в файле magic.txt в репозитории исходного кода SQLite.

См. также PRAGMA user_version.

PRAGMA schema.auto_vacuum;
PRAGMA schema.auto_vacuum = 0 | NONE | 1 | FULL | 2 | INCREMENTAL;

Запрос или изменение режима автоочистки базы данных.

По умолчанию для автоочистки задано значение 0, или «none», если не используется параметр компиляции SQLITE_DEFAULT_AUTOVACUUM. Значение «none» означает, что автоочистка отключена. Если автоочистка отключена и из базы данных удаляются данные, размер файла базы данных остаётся прежним. Неиспользуемые страницы файла базы данных добавляются в «список свободных страниц» и используются повторно при последующих вставках. Таким образом, место в файле базы данных не теряется. Однако размер файла базы данных не уменьшается. В этом режиме для перестроения всего файла базы данных и освобождения неиспользуемого дискового пространства можно использовать команду VACUUM.

Если для режима автоочистки задано значение 1, или «full», страницы из списка свободных страниц перемещаются в конец файла базы данных, а файл усекается для удаления этих страниц при фиксации каждой транзакции. Однако обратите внимание: автоочистка только удаляет страницы из списка свободных страниц в конце файла. Автоочистка не дефрагментирует базу данных и не переупаковывает отдельные страницы базы данных так, как это делает команда VACUUM. Более того, поскольку она перемещает страницы внутри файла, автоочистка может фактически усилить фрагментацию.

Автоочистка возможна только в том случае, если в базе данных хранится дополнительная информация, позволяющая проследить путь от каждой страницы базы данных к ссылающейся на неё странице. Поэтому автоочистку необходимо включить до создания таблиц. Включить или отключить автоочистку после создания таблицы невозможно.

Если значение auto_vacuum равно 2, или «incremental», то дополнительная информация, необходимая для автоочистки, хранится в файле базы данных, но автоочистка не выполняется автоматически при каждой фиксации транзакции, как это происходит при auto_vacuum=full. В инкрементном режиме для выполнения автоочистки необходимо вызвать отдельную команду PRAGMA incremental_vacuum.

Режим автоочистки подключения к базе данных можно в любое время переключать между полным и инкрементным. Однако переключение с режима «none» на «full» или «incremental» возможно только для новой базы данных (в которой ещё не создано таблиц) либо после выполнения команды VACUUM. Чтобы изменить режим автоочистки, сначала используйте PRAGMA auto_vacuum для задания нового режима, а затем вызовите команду VACUUM, чтобы реорганизовать весь файл базы данных. Для переключения с режима «full» или «incremental» обратно на «none» всегда требуется выполнить VACUUM, даже для пустой базы данных.

Если вызвать PRAGMA auto_vacuum без аргументов, он вернёт текущий режим auto_vacuum.

PRAGMA automatic_index;
PRAGMA automatic_index = boolean;

Запрос, включение или отключение возможности автоматического индексирования.

Автоматическое индексирование включено по умолчанию начиная с версии 3.7.17 (2013-05-20), однако в будущих выпусках SQLite это может измениться.

PRAGMA busy_timeout;
PRAGMA busy_timeout = milliseconds;

Запрос или изменение значения тайм-аута ожидания. Эта PRAGMA служит альтернативой интерфейсу языка C sqlite3_busy_timeout() и предоставляется в виде PRAGMA для использования с языковыми привязками, которые не обеспечивают прямой доступ к sqlite3_busy_timeout().

Для каждого подключения к базе данных может быть задан только один обработчик занятости. Эта PRAGMA задаёт обработчик занятости для процесса, возможно перезаписывая ранее заданный обработчик.

PRAGMA schema.cache_size;
PRAGMA schema.cache_size = pages;
PRAGMA schema.cache_size = -kibibytes;

Запрос или изменение рекомендуемого максимального числа страниц базы данных, которые SQLite будет одновременно хранить в памяти для каждого открытого файла базы данных. Соблюдение этой рекомендации зависит от кэша страниц, определяемого приложением. Встроенный в SQLite кэш страниц выполняет этот запрос, однако альтернативные реализации кэша страниц, определяемые приложением, могут интерпретировать рекомендуемый размер кэша по-разному или полностью его игнорировать. По умолчанию рекомендуемый размер кэша равен -2000, что ограничивает его объём 2048000 байтами памяти. Значение рекомендуемого размера кэша по умолчанию можно изменить с помощью параметров компиляции SQLITE_DEFAULT_CACHE_SIZE. Для временной базы данных рекомендуемый размер кэша по умолчанию равен 0 страниц.

Если аргумент N положителен, рекомендуемый размер кэша устанавливается равным N. Если аргумент N отрицателен, число страниц кэша корректируется так, чтобы при текущем размере страницы для них требовалось приблизительно abs(N*1024) байт памяти. SQLite запоминает число страниц в кэше, а не объём используемой памяти. Поэтому, если задать размер кэша отрицательным числом, а затем изменить размер страницы (с помощью команды PRAGMA page_size), максимальный объём памяти кэша увеличится или уменьшится пропорционально изменению размера страницы.

Примечание о совместимости с предыдущими версиями: До версии 3.7.10 (2012-01-16) значение cache_size при отрицательном N обрабатывалось иначе. В более ранних версиях число страниц в кэше устанавливалось равным абсолютному значению N.

При изменении размера кэша с помощью PRAGMA cache_size это изменение действует только в течение текущего сеанса. После закрытия и повторного открытия базы данных размер кэша возвращается к значению по умолчанию.

Реализация кэша страниц по умолчанию не выделяет весь объём памяти кэша сразу. Память кэша выделяется небольшими блоками по мере необходимости. Параметр page_cache задаёт (рекомендуемую) верхнюю границу объёма памяти, который может использовать кэш, а не объём памяти, который он будет использовать постоянно. Так ведёт себя реализация кэша страниц по умолчанию, однако кэш страниц, определённый приложением, может работать иначе, если это необходимо.

PRAGMA cache_spill;
PRAGMA cache_spill=boolean;
PRAGMA schema.cache_spill=N;

Прагма cache_spill включает или отключает возможность сбрасывать изменённые страницы кэша в файл базы данных в ходе транзакции. Параметр cache_spill включён по умолчанию, и большинству приложений следует оставить это значение, поскольку сброс страниц кэша обычно полезен. Однако при сбросе страниц кэша на файл базы данных устанавливается эксклюзивная блокировка. Поэтому некоторым приложениям с длительными транзакциями большого объёма может потребоваться отключить сброс страниц кэша, чтобы приложение не устанавливало эксклюзивную блокировку базы данных до момента выполнения COMMIT транзакции.

Форма этой прагмы "PRAGMA cache_spill=N" задаёт минимальный пороговый размер кэша, при достижении которого выполняется сброс. Чтобы сброс состоялся, число страниц в кэше должно превысить как пороговое значение cache_spill, так и максимальный размер кэша, заданный оператором PRAGMA cache_size.

Форма этой прагмы "PRAGMA cache_spill=boolean" применяется ко всем базам данных, подключённым к соединению с базой данных. Но форма оператора "PRAGMA cache_spill=N" применяется только к схеме "main" или к другой схеме, указанной в операторе.

PRAGMA case_sensitive_like = boolean;

Оператор LIKE по умолчанию не учитывает регистр ASCII-символов. Поэтому по умолчанию выражение 'a' LIKE 'A' истинно. Прагма case_sensitive_like устанавливает новую функцию LIKE, определённую приложением, с учётом или без учёта регистра — в зависимости от значения прагмы case_sensitive_like. Если case_sensitive_like отключена, используется стандартное поведение LIKE. Если case_sensitive_like включена, регистр учитывается. Например, 'a' LIKE 'A' ложно, а 'a' LIKE 'a' по-прежнему истинно.

Эта прагма использует sqlite3_create_function() для переопределения функций LIKE и GLOB, что может заменить предыдущие реализации LIKE и GLOB, зарегистрированные приложением. Прагма изменяет только поведение оператора SQL LIKE. Она не меняет поведение интерфейса языка C sqlite3_strlike(), который всегда не учитывает регистр.

ПРЕДУПРЕЖДЕНИЕ: Если оператор LIKE используется где-либо в схеме базы данных, например в ограничении CHECK, в индексе по выражению или в предложении WHERE частичного индекса, изменение определения оператора LIKE с помощью этой PRAGMA может привести к тому, что база данных будет выглядеть повреждённой. PRAGMA integrity_check сообщит об ошибках. На самом деле база данных не повреждена: если вернуть поведение LIKE к тому, которое было при создании схемы и заполнении базы данных, проблема исчезнет. Если LIKE используется только в индексах, проблему можно устранить, выполнив REINDEX. Тем не менее использовать прагму case_sensitive_like не рекомендуется.

Эта прагма устарела и существует только для обеспечения обратной совместимости. Новым приложениям следует избегать её использования. Старым приложениям следует прекратить использовать эту прагму при первой возможности. Эту прагму можно исключить из сборки, если SQLite компилируется с параметром SQLITE_OMIT_DEPRECATED.

PRAGMA cell_size_check
PRAGMA cell_size_check = boolean;

Прагма cell_size_check включает или отключает дополнительную проверку целостности страниц B-дерева базы данных при их первоначальном чтении с диска. При включённой проверке размера ячеек повреждение базы данных обнаруживается раньше и с меньшей вероятностью «распространяется». Однако дополнительная проверка немного снижает производительность, поэтому по умолчанию она отключена.

PRAGMA checkpoint_fullfsync
PRAGMA checkpoint_fullfsync = boolean;

Запрашивает или изменяет флаг fullfsync для операций контрольной точки. Если этот флаг установлен, во время операций контрольной точки в системах, поддерживающих F_FULLFSYNC, используется метод синхронизации F_FULLFSYNC. По умолчанию флаг checkpoint_fullfsync отключён. Только Mac OS-X поддерживает F_FULLFSYNC.

Если установлен флаг fullfsync, метод синхронизации F_FULLFSYNC используется для всех операций синхронизации, и настройка checkpoint_fullfsync не имеет значения.

PRAGMA collation_list;

Возвращает список последовательностей сортировки, определённых для текущего соединения с базой данных.

PRAGMA compile_options;

Эта прагма возвращает имена параметров компиляции, использованных при сборке SQLite, по одному параметру в каждой строке. Префикс "SQLITE_" в возвращаемых именах параметров опускается. См. также интерфейс C/C++ sqlite3_compileoption_get() и функции SQL sqlite_compileoption_get().

PRAGMA count_changes;
PRAGMA count_changes = boolean;

Запрашивает или изменяет флаг count-changes. Обычно, если флаг count-changes не установлен, операторы INSERT, UPDATE и DELETE не возвращают данные. Если флаг count-changes установлен, каждая из этих команд возвращает одну строку данных с одним целочисленным значением — числом строк, добавленных, изменённых или удалённых командой. Возвращаемое число изменений не включает вставки, изменения или удаления, выполненные триггерами, изменения, автоматически внесённые действиями внешних ключей, а также обновления, вызванные оператором upsert.

Другой способ получить число изменённых строк — использовать интерфейсы sqlite3_changes() или sqlite3_total_changes(). Однако есть одно тонкое различие. Если INSERT, UPDATE или DELETE выполняется для представления с помощью триггера INSTEAD OF, прагма count_changes сообщает число строк представления, вызвавших срабатывание триггера, тогда как sqlite3_changes() и sqlite3_total_changes() этого не делают.

Эта прагма устарела и существует только для обеспечения обратной совместимости. Новым приложениям следует избегать её использования. Старым приложениям следует прекратить использовать эту прагму при первой возможности. Эту прагму можно исключить из сборки, если SQLite компилируется с параметром SQLITE_OMIT_DEPRECATED.

PRAGMA data_store_directory;
PRAGMA data_store_directory = 'directory-name';

Запрашивает или изменяет значение глобальной переменной sqlite3_data_directory, которую используют серверные части интерфейса операционной системы Windows для определения места хранения файлов баз данных, указанных с помощью относительного пути.

Изменение настройки data_store_directory не является потокобезопасным. Никогда не изменяйте настройку data_store_directory, если в другом потоке приложения в это же время используется какой-либо интерфейс SQLite. Это приведёт к неопределённому поведению. Изменение настройки data_store_directory записывает значение в глобальную переменную sqlite3_data_directory, которая не защищена мьютексом.

Этот механизм предусмотрен для WinRT, в которой отсутствует механизм ОС для чтения или изменения текущего рабочего каталога. Не рекомендуется использовать эту прагму в каком-либо другом контексте; в будущих выпусках её использование может быть запрещено.

Эта прагма объявлена устаревшей и существует только для обратной совместимости. Новым приложениям следует избегать использования этой прагмы. Старым приложениям следует прекратить её использование при первой возможности. Эту прагму можно исключить из сборки, если SQLite скомпилирована с использованием SQLITE_OMIT_DEPRECATED.

PRAGMA schema.data_version;

Команда «PRAGMA data_version» позволяет определить, был ли изменён файл базы данных. Интерактивные программы, которые хранят содержимое базы данных в памяти или отображают его на экране, могут использовать команду PRAGMA data_version, чтобы определить, нужно ли сбросить и перезагрузить данные в памяти или обновить изображение на экране.

Целочисленные значения, возвращаемые двумя вызовами «PRAGMA data_version» для одного и того же соединения, будут различаться, если за это время изменения были зафиксированы в базе данных другим соединением. Значение «PRAGMA data_version» не меняется при фиксации изменений в том же соединении с базой данных. Поведение «PRAGMA data_version» одинаково для всех соединений с базой данных, в том числе для соединений в отдельных процессах и соединений с базой данных, использующих общий кэш.

Значение «PRAGMA data_version» является локальным свойством каждого соединения с базой данных, поэтому значения, возвращаемые двумя одновременными вызовами «PRAGMA data_version» для разных соединений с базой данных, часто различаются, даже если базовая база данных идентична. Имеет смысл сравнивать только значения «PRAGMA data_version», возвращённые одним и тем же соединением с базой данных в два разных момента времени.

PRAGMA database_list;

Эта прагма работает как запрос и возвращает по одной строке для каждой базы данных, подключённой к текущему соединению. Во втором столбце указано «main» для основного файла базы данных, «temp» для файла базы данных, используемого для хранения объектов TEMP, или имя подключённой базы данных для других файлов базы данных. В третьем столбце указано имя самого файла базы данных или пустая строка, если база данных не связана с файлом.

Эта прагма запрашивает или задаёт рекомендуемое максимальное количество страниц дискового кэша, выделяемого для каждого открытого файла базы данных. Отличие этой прагмы от cache_size заключается в том, что заданное здесь значение сохраняется при повторном подключении к базе данных. Значение размера кэша по умолчанию хранится в 4-байтовом целом числе в порядке байтов от старшего к младшему, расположенном по смещению 48 в заголовке файла базы данных.

Эта прагма объявлена устаревшей и существует только для обратной совместимости. Новым приложениям следует избегать использования этой прагмы. Старым приложениям следует прекратить её использование при первой возможности. Эту прагму можно исключить из сборки, если SQLite скомпилирована с использованием SQLITE_OMIT_DEPRECATED.

PRAGMA defer_foreign_keys
PRAGMA defer_foreign_keys = boolean;

Если прагма defer_foreign_keys PRAGMA включена, проверка всех ограничений внешних ключей откладывается до фиксации самой внешней транзакции. По умолчанию прагма defer_foreign_keys выключена, поэтому проверка ограничений внешних ключей откладывается только в том случае, если они созданы как «DEFERRABLE INITIALLY DEFERRED». Прагма defer_foreign_keys автоматически выключается при каждой операции COMMIT или ROLLBACK. Поэтому её необходимо отдельно включать для каждой транзакции. Разумеется, эта прагма имеет смысл только в том случае, если ограничения внешних ключей включены.

Во время транзакции можно использовать интерфейс языка C sqlite3_db_status(db,SQLITE_DBSTATUS_DEFERRED_FKS,...) для определения наличия отложенных и неразрешённых ограничений внешних ключей.

PRAGMA empty_result_callbacks;
PRAGMA empty_result_callbacks = boolean;

Запрашивает или изменяет флаг empty-result-callbacks.

Флаг empty-result-callbacks влияет только на API sqlite3_exec(). Обычно, если флаг empty-result-callbacks выключен, функция обратного вызова, переданная в sqlite3_exec(), не вызывается для команд, возвращающих ноль строк данных. Если в такой ситуации empty-result-callbacks включён, функция обратного вызова вызывается ровно один раз, а её третий параметр равен 0 (NULL). Это позволяет программам, использующим API sqlite3_exec(), получать имена столбцов даже в том случае, если запрос не возвращает данных.

Эта прагма объявлена устаревшей и существует только для обратной совместимости. Новым приложениям следует избегать использования этой прагмы. Старым приложениям следует прекратить её использование при первой возможности. Эту прагму можно исключить из сборки, если SQLite скомпилирована с использованием SQLITE_OMIT_DEPRECATED.

PRAGMA encoding;
PRAGMA encoding = 'UTF-8';
PRAGMA encoding = 'UTF-16';
PRAGMA encoding = 'UTF-16le';
PRAGMA encoding = 'UTF-16be';

В первой форме, если основная база данных уже создана, эта прагма возвращает использованную в ней кодировку текста: одну из «UTF-8», «UTF-16le» (кодировка UTF-16 с порядком байтов от младшего к старшему) или «UTF-16be» (кодировка UTF-16 с порядком байтов от старшего к младшему). Если основная база данных ещё не создана, возвращаемое значение — это кодировка текста, которая будет использоваться для создания основной базы данных в рамках этого сеанса.

Вторая, третья, четвёртая и пятая формы этой прагмы задают кодировку, в которой будет создана основная база данных, если она будет создана в рамках этого сеанса. Строка «UTF-16» интерпретируется как «кодировка UTF-16 с порядком байтов, принятым в данной системе». Изменить кодировку текста базы данных после её создания невозможно; любая попытка сделать это будет молча проигнорирована.

Если кодировка не задана с помощью этой прагмы, для создаваемой основной базы данных по умолчанию используется кодировка, определяемая API, применяемым для открытия соединения.

После того как для базы данных задана кодировка, изменить её нельзя.

Базы данных, созданные командой ATTACH, всегда используют ту же кодировку, что и основная база данных. Попытка выполнить ATTACH для базы данных с кодировкой текста, отличающейся от кодировки базы данных «main», завершится ошибкой.

PRAGMA schema.foreign_key_check;
PRAGMA schema.foreign_key_check(table-name);

Прагма foreign_key_check проверяет базу данных или таблицу с именем "table-name" на наличие нарушенных ограничений внешнего ключа. Прагма foreign_key_check возвращает одну строку для каждого нарушения внешнего ключа. Каждая строка результата содержит четыре столбца. Первый столбец — имя таблицы, содержащей предложение REFERENCES. Второй столбец — rowid строки, содержащей недопустимое предложение REFERENCES, или NULL, если дочерняя таблица является таблицей WITHOUT ROWID. Третий столбец — имя таблицы, на которую ссылаются. Четвёртый столбец — индекс конкретного ограничения внешнего ключа, которое было нарушено. Четвёртый столбец результата прагмы foreign_key_check содержит то же целое число, что и первый столбец результата прагмы foreign_key_list. Если указано имя "table-name", проверяются только ограничения внешнего ключа, созданные предложениями REFERENCES в операторе CREATE TABLE для таблицы table-name.

PRAGMA foreign_key_list(table-name);

Эта прагма возвращает одну строку для каждого ограничения внешнего ключа, созданного предложением REFERENCES в операторе CREATE TABLE для таблицы "table-name".

PRAGMA foreign_keys;
PRAGMA foreign_keys = boolean;

Проверяет, включает или отключает применение ограничений внешнего ключа.

Эта прагма не действует внутри транзакции; применение ограничений внешнего ключа можно включить или отключить, только если нет незавершённых операторов BEGIN или SAVEPOINT.

Изменение настройки foreign_keys влияет на выполнение всех операторов, подготовленных с использованием соединения с базой данных, в том числе подготовленных до изменения настройки. Любые существующие операторы, подготовленные с использованием устаревшего интерфейса sqlite3_prepare(), могут завершиться ошибкой SQLITE_SCHEMA после изменения настройки foreign_keys.

Начиная с версии 3.6.19 SQLite, применение внешних ключей по умолчанию отключено. Однако в будущих выпусках SQLite это может измениться. Настройку применения внешних ключей по умолчанию можно указать во время компиляции с помощью макроса препроцессора SQLITE_DEFAULT_FOREIGN_KEYS. Чтобы избежать возможных проблем в будущем, приложениям следует задавать флаг применения внешних ключей в соответствии со своими требованиями и не полагаться на настройку по умолчанию.

PRAGMA schema.freelist_count;

Возвращает количество неиспользуемых страниц в файле базы данных.

PRAGMA full_column_names;
PRAGMA full_column_names = boolean;

Проверяет или изменяет флаг full_column_names. Этот флаг вместе с флагом short_column_names определяет, как SQLite присваивает имена столбцам результата операторов SELECT. Имена столбцов результата определяются по следующим правилам, применяемым в указанном порядке:

1. Если в результате есть предложение AS, именем столбца становится правая часть предложения AS.

2. Если результат представляет собой общее выражение, а не только имя столбца исходной таблицы, именем результата становится копия текста выражения.

3. Если прагма short_column_names включена, именем результата становится имя столбца исходной таблицы без префикса с именем исходной таблицы: COLUMN.

4. Если обе прагмы — short_column_names и full_column_names — отключены, применяется правило (2).

5. Именем столбца результата становится сочетание имени исходной таблицы и имени исходного столбца: TABLE.COLUMN

Эта прагма устарела и существует только для обратной совместимости. Новым приложениям не следует использовать эту прагму. Старым приложениям следует прекратить её использование при первой возможности. Эту прагму можно исключить из сборки, если SQLite скомпилирована с параметром SQLITE_OMIT_DEPRECATED.

PRAGMA fullfsync
PRAGMA fullfsync = boolean;

Проверяет или изменяет флаг fullfsync. Этот флаг определяет, используется ли метод синхронизации F_FULLFSYNC в системах, которые его поддерживают. По умолчанию флаг fullfsync выключен. F_FULLFSYNC поддерживается только в Mac OS X.

См. также checkpoint_fullfsync.

PRAGMA function_list;

Эта прагма возвращает список функций SQL, известных соединению с базой данных. Каждая строка результата описывает одну сигнатуру вызова одной функции SQL. Некоторые функции SQL представлены в наборе результатов несколькими строками, если их можно, например, вызывать с разным количеством аргументов или передавать им текст в различных кодировках.

PRAGMA hard_heap_limit
PRAGMA hard_heap_limit=N

Эта прагма вызывает интерфейс sqlite3_hard_heap_limit64() с аргументом N, если N указан и является положительным целым числом, меньшим текущего жёсткого ограничения кучи. Прагма hard_heap_limit всегда возвращает то же целое число, что и функция на языке C sqlite3_hard_heap_limit64(-1). Иными словами, она всегда возвращает значение жёсткого ограничения кучи, установленное после всех изменений, внесённых этой прагмой.

Эта прагма может только уменьшить ограничение кучи, но не увеличить его. Для увеличения ограничения кучи необходимо использовать интерфейс на языке C sqlite3_hard_heap_limit64().

См. также прагму soft_heap_limit.

PRAGMA ignore_check_constraints = boolean;

Эта прагма включает или отключает проверку ограничений CHECK. По умолчанию настройка выключена, то есть ограничения CHECK проверяются.

PRAGMA schema.incremental_vacuum(N);
PRAGMA schema.incremental_vacuum;

Прагма incremental_vacuum удаляет из списка свободных страниц до N страниц. Файл базы данных уменьшается на такое же количество страниц. Прагма incremental_vacuum не действует, если база данных работает не в режиме auto_vacuum=incremental или если в списке свободных страниц нет страниц. Если в списке свободных страниц меньше N страниц, если N меньше 1 или если аргумент "(N)" не указан, очищается весь список свободных страниц.

PRAGMA schema.index_info(index-name);

Эта прагма возвращает по одной строке для каждого ключевого столбца в указанном индексе. Ключевой столбец — это столбец, имя которого указано в операторе индекса CREATE INDEX либо в ограничении UNIQUE или PRIMARY KEY, создавшем индекс. Записи индекса обычно также содержат вспомогательные столбцы, указывающие на индексируемую строку таблицы. Вспомогательные столбцы индекса не отображаются прагмой index_info, но перечислены в прагме index_xinfo.

Выходные столбцы прагмы index_info:

1. Порядковый номер столбца в индексе. (0 означает крайний левый.)
2. Порядковый номер столбца в индексируемой таблице. Значение -1 означает rowid, а значение -2 означает, что используется выражение.
3. Имя индексируемого столбца. Значение этого столбца равно NULL, если столбец является rowid или выражением.

Если индекса с именем index-name нет, но существует таблица WITHOUT ROWID с таким именем, то (начиная с SQLite версии 3.30.0 от 2019-10-04) эта прагма возвращает столбцы PRIMARY KEY таблицы WITHOUT ROWID в том виде, в каком они используются в записях базового b-дерева, то есть без повторяющихся столбцов.

PRAGMA schema.index_list(table-name);

Эта прагма возвращает по одной строке для каждого индекса, связанного с указанной таблицей.

Выходные столбцы прагмы index_list:

1. Порядковый номер, назначенный каждому индексу для внутреннего отслеживания.
2. Имя индекса.
3. "1", если индекс является UNIQUE, и "0" в противном случае.
4. "c", если индекс создан оператором CREATE INDEX, "u", если индекс создан ограничением UNIQUE, или "pk", если индекс создан ограничением PRIMARY KEY.
5. "1", если индекс является частичным индексом, и "0" в противном случае.

PRAGMA schema.index_xinfo(index-name);

Эта прагма возвращает сведения о каждом столбце индекса. В отличие от прагмы index_info, эта прагма возвращает сведения обо всех столбцах индекса, а не только о ключевых. (Ключевой столбец — это столбец, имя которого указано в операторе индекса CREATE INDEX либо в ограничении UNIQUE или PRIMARY KEY, создавшем индекс. Вспомогательные столбцы — это дополнительные столбцы, необходимые для поиска записи таблицы, соответствующей каждой записи индекса.)

Выходные столбцы прагмы index_xinfo:

1. Порядковый номер столбца в индексе. (0 означает крайний левый. Ключевые столбцы располагаются перед вспомогательными.)
2. Порядковый номер столбца в индексируемой таблице или -1, если столбец индекса — это rowid индексируемой таблицы, и -2, если индекс построен по выражению.
3. Имя индексируемого столбца или NULL, если столбец индекса — это rowid индексируемой таблицы либо выражение.
4. 1, если столбцы индекса сортируются в обратном порядке (DESC), и 0 в противном случае.
5. Имя последовательности сортировки, используемой для сравнения значений в столбце индекса.
6. 1, если столбец индекса является ключевым, и 0, если он является вспомогательным.

Если индекса с именем index-name нет, но существует таблица WITHOUT ROWID с таким именем, то (начиная с SQLite версии 3.30.0 от 2019-10-04) эта прагма возвращает столбцы таблицы WITHOUT ROWID в том виде, в каком они используются в записях базового b-дерева, то есть сначала столбцы PRIMARY KEY без дубликатов, а затем столбцы данных.

PRAGMA schema.integrity_check;
PRAGMA schema.integrity_check(N)
PRAGMA schema.integrity_check(TABLENAME)

Эта прагма выполняет низкоуровневую проверку форматирования и целостности базы данных. Прагма integrity_check ищет:

• Записи таблиц или индексов, расположенные не по порядку
• Неправильно отформатированные записи
• Отсутствующие страницы
• Отсутствующие или лишние записи индекса
• Ошибки ограничений UNIQUE, CHECK и NOT NULL
• Целостность списка свободных страниц
• Области базы данных, используемые более одного раза или не используемые вовсе

Если прагма integrity_check обнаруживает проблемы, возвращаются строки с описаниями проблем (в нескольких строках, по одному столбцу в каждой). Прагма integrity_check вернет не более N ошибок, после чего анализ будет остановлен; значение N по умолчанию равно 100. Если прагма integrity_check не обнаруживает ошибок, возвращается одна строка со значением 'ok'.

Обычно проверяется весь файл базы данных. Однако, если аргументом является TABLENAME, проверяется только указанная таблица и связанные с ней индексы. Это называется «частичной проверкой целостности». Поскольку проверяется лишь часть базы данных, невозможно обнаружить такие ошибки, как неиспользуемые области файла или повторное использование одной и той же области файла двумя или более таблицами. Список свободных страниц проверяется при частичной проверке целостности только в том случае, если TABLENAME — это sqlite_schema или один из ее псевдонимов. Поддержка частичных проверок целостности добавлена в версии 3.33.0 (2020-08-14).

PRAGMA integrity_check не обнаруживает ошибки FOREIGN KEY. Для поиска ошибок в ограничениях FOREIGN KEY используйте команду PRAGMA foreign_key_check.

См. также команду PRAGMA quick_check, которая выполняет большую часть проверок PRAGMA integrity_check, но работает намного быстрее.

PRAGMA schema.journal_mode;
PRAGMA schema.journal_mode = DELETE | TRUNCATE | PERSIST | MEMORY | WAL | OFF

Эта прагма запрашивает или задает режим журнала для баз данных, связанных с текущим подключением к базе данных.

Первая форма этой прагмы запрашивает текущий режим ведения журнала для database. Если database не указан, запрашивается база данных "main".

Вторая форма изменяет режим ведения журнала для "database" или для всех присоединенных баз данных, если "database" не указан. Возвращается новый режим журнала. Если изменить режим журнала не удалось, возвращается исходный режим.

Режим ведения журнала DELETE используется по умолчанию. В режиме DELETE журнал отката удаляется по завершении каждой транзакции. Фактически именно операция удаления приводит к фиксации транзакции. (Дополнительные сведения см. в документе Атомарная фиксация в SQLite.)

В режиме ведения журнала TRUNCATE транзакции фиксируются путем усечения журнала отката до нулевой длины, а не его удаления. Во многих системах усечение файла происходит гораздо быстрее, чем его удаление, поскольку при этом не требуется изменять содержащий его каталог.

Режим журналирования PERSIST предотвращает удаление журнала отката в конце каждой транзакции. Вместо этого заголовок журнала перезаписывается нулями. Это не позволит другим подключениям к базе данных выполнить откат по этому журналу. Режим журналирования PERSIST полезен для оптимизации на платформах, где удаление или усечение файла обходится гораздо дороже, чем перезапись первого блока файла нулями. См. также: PRAGMA journal_size_limit и SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT.

Режим журналирования MEMORY хранит журнал отката в энергозависимой оперативной памяти. Это позволяет сократить операции ввода-вывода на диске, но снижает безопасность и целостность базы данных. Если приложение, использующее SQLite, аварийно завершится в середине транзакции при включённом режиме журналирования MEMORY, файл базы данных, скорее всего, будет повреждён.

Режим журналирования WAL использует журнал предварительной записи вместо журнала отката для реализации транзакций. Режим журналирования WAL является постоянным: после включения он сохраняется при нескольких подключениях к базе данных, а также после закрытия и повторного открытия базы данных. Доступ к базе данных в режиме журналирования WAL возможен только с помощью SQLite версии 3.7.0 (2010-07-21) или новее.

Режим журналирования OFF полностью отключает журнал отката. Журнал отката никогда не создаётся, а значит, никогда не возникает необходимости его удалять. Режим журналирования OFF отключает возможности атомарной фиксации и отката SQLite. Команда ROLLBACK больше не работает и ведёт себя неопределённым образом. Приложениям следует избегать использования команды ROLLBACK, когда включён режим журналирования OFF. Если приложение аварийно завершится в середине транзакции при включённом режиме журналирования OFF, файл базы данных, скорее всего, будет повреждён. Без журнала оператор не может отменить частично выполненные операции после ошибки ограничения. Это также может оставить базу данных в повреждённом состоянии. Например, если дублирующаяся запись приводит к сбою оператора CREATE UNIQUE INDEX на полпути выполнения, останется частично созданный и, следовательно, повреждённый индекс. Поскольку режим журналирования OFF позволяет повредить файл базы данных с помощью обычного SQL, он отключается, когда включён параметр SQLITE_DBCONFIG_DEFENSIVE.

Обратите внимание, что для базы данных в памяти режим journal_mode может быть только MEMORY или OFF, и изменить его на другое значение нельзя. Попытка изменить режим journal_mode базы данных в памяти на любое значение, кроме MEMORY или OFF, игнорируется. Также обратите внимание, что режим journal_mode нельзя изменить во время активной транзакции.

PRAGMA schema.journal_size_limit
PRAGMA schema.journal_size_limit = N ;

Если подключение к базе данных работает в режиме эксклюзивной блокировки или в режиме постоянного журнала (PRAGMA journal_mode=persist), то после фиксации транзакции файл журнала отката может остаться в файловой системе. Это повышает производительность последующих транзакций, поскольку перезапись существующего файла выполняется быстрее, чем добавление данных в файл, но при этом расходуется место в файловой системе. После крупной транзакции (например, VACUUM) файл журнала отката может занимать очень много места.

Аналогично, в режиме WAL файл журнала предварительной записи не усекается после контрольной точки. Вместо этого SQLite повторно использует существующий файл для последующих записей WAL, поскольку перезапись выполняется быстрее, чем добавление данных.

Прагму journal_size_limit можно использовать, чтобы ограничить размер файлов журнала отката и WAL, остающихся в файловой системе после транзакций или контрольных точек. Каждый раз при фиксации транзакции или сбросе файла WAL SQLite сравнивает размер оставшегося в файловой системе файла журнала отката или WAL с пределом размера, заданным этой прагмой, и, если файл журнала или WAL превышает предел, усекает его до этого размера.

Вторая приведённая выше форма прагмы используется для задания нового предела в байтах для указанной базы данных. Отрицательное число означает отсутствие предела. Чтобы всегда усекать журналы отката и файлы WAL до минимального размера, задайте для journal_size_limit значение zero. Первая и вторая формы прагмы, приведённые выше, возвращают одну строку результата с одним целочисленным столбцом — значением предела размера журнала в байтах. По умолчанию предел размера журнала равен -1 (без ограничения). Макрос препроцессора SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT позволяет изменить предел размера журнала по умолчанию во время компиляции.

Эта pragma действует только на одну базу данных, указанную перед именем pragma (или на базу данных "main", если база данных не указана). Нельзя изменить предел размера журнала для всех подключённых баз данных с помощью одного оператора PRAGMA. Для каждой подключённой базы данных предел размера необходимо задавать отдельно.

PRAGMA legacy_alter_table;
PRAGMA legacy_alter_table = boolean

Эта прагма задаёт или запрашивает значение флага legacy_alter_table. Если этот флаг включён, команда ALTER TABLE RENAME (для изменения имени таблицы) работает так же, как в SQLite 3.24.0 (2018-06-04) и более ранних версиях. В частности, когда этот флаг включён, команда ALTER TABLE RENAME изменяет только первое вхождение имени таблицы в её операторе CREATE TABLE и в связанных с ним операторах CREATE INDEX и CREATE TRIGGER. Остальные ссылки на таблицу не изменяются, в том числе:

• Ссылки на таблицу в телах триггеров и представлений.
• Ссылки на таблицу в ограничениях CHECK исходного оператора CREATE TABLE.
• Ссылки на таблицу в предложениях WHERE частичных индексов.

Эта прагма предусмотрена в качестве обходного решения для старых программ, содержащих код, который ожидает неполного поведения команды ALTER TABLE RENAME, характерного для старых версий SQLite. В новых приложениях этот флаг следует оставлять выключенным.

Для совместимости со старыми реализациями виртуальных таблиц этот флаг временно включается во время выполнения метода sqlite3_module.xRename. Значение этого флага восстанавливается после завершения метода sqlite3_module.xRename.

Поведение устаревшей команды alter table также можно включать и выключать с помощью параметра SQLITE_DBCONFIG_LEGACY_ALTER_TABLE интерфейса sqlite3_db_config().

Поведение устаревшей команды alter table задаётся отдельно для каждого подключения. Включение или выключение этой функции влияет на все файлы подключённых баз данных в рамках подключения к базе данных. Эта настройка не сохраняется. Изменение настройки в одном подключении не влияет на другие подключения.

PRAGMA legacy_file_format;

Эта прагма больше не работает. Она стала пустой операцией. Возможности, ранее предоставлявшиеся с помощью PRAGMA legacy_file_format, теперь доступны через параметр SQLITE_DBCONFIG_LEGACY_FILE_FORMAT интерфейса языка C sqlite3_db_config().

PRAGMA schema.locking_mode;
PRAGMA schema.locking_mode = NORMAL | EXCLUSIVE

Эта прагма задаёт или запрашивает режим блокировки подключения к базе данных. Режим блокировки может быть NORMAL или EXCLUSIVE.

В режиме блокировки NORMAL (по умолчанию, если он не переопределён во время компиляции с помощью SQLITE_DEFAULT_LOCKING_MODE) подключение к базе данных снимает блокировку файла базы данных по завершении каждой транзакции чтения или записи. Когда для режима блокировки задано значение EXCLUSIVE, подключение к базе данных никогда не снимает блокировки файла. При первом чтении базы данных в режиме EXCLUSIVE устанавливается и удерживается разделяемая блокировка. При первой записи в базу данных устанавливается и удерживается исключительная блокировка.

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

Существует три причины задавать режим блокировки EXCLUSIVE.

1. Приложение хочет запретить другим процессам доступ к файлу базы данных.
2. Количество системных вызовов для операций с файловой системой сокращается, что может привести к небольшому повышению производительности.
3. К базам данных WAL можно обращаться в режиме EXCLUSIVE без использования общей памяти. (Дополнительная информация)

Если в прагме locking_mode указана конкретная база данных, например:

 PRAGMA main.locking_mode=EXCLUSIVE; 

то режим блокировки применяется только к указанной базе данных. Если перед ключевым словом "locking_mode" не указано имя базы данных, режим блокировки применяется ко всем базам данных, включая любые новые базы данных, добавленные последующими командами ATTACH.

Для базы данных "temp" (в которой хранятся таблицы и индексы TEMP) и баз данных в памяти всегда используется режим исключительной блокировки. Режим блокировки для temp и баз данных в памяти изменить нельзя. Для всех остальных баз данных по умолчанию используется обычный режим блокировки, на который влияет эта прагма.

Если при первом переходе в режим журнала WAL установлен режим блокировки EXCLUSIVE, его нельзя изменить на NORMAL до выхода из режима журнала WAL. Если при первом переходе в режим журнала WAL установлен режим блокировки NORMAL, его можно в любой момент изменить на EXCLUSIVE и обратно без необходимости выходить из режима журнала WAL.

PRAGMA schema.max_page_count;
PRAGMA schema.max_page_count = N;

Запрашивает или задаёт максимальное количество страниц в файле базы данных. Обе формы прагмы возвращают максимальное количество страниц. Вторая форма пытается изменить максимальное количество страниц. Максимальное количество страниц нельзя уменьшить ниже текущего размера базы данных.

PRAGMA schema.mmap_size;
PRAGMA schema.mmap_size=N

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

Аргумент N — это максимальное количество байтов файла базы данных, к которым будет выполняться доступ с помощью ввода-вывода с отображением в память. Если N равно нулю, ввод-вывод с отображением в память отключается. Если N отрицательно, предел возвращается к значению по умолчанию, определяемому последним вызовом sqlite3_config(SQLITE_CONFIG_MMAP_SIZE), или к значению по умолчанию, заданному во время компиляции с помощью SQLITE_DEFAULT_MMAP_SIZE, если при запуске предел не был задан.

Инструкция PRAGMA mmap_size никогда не увеличивает объём адресного пространства, используемого для ввода-вывода с отображением в память, выше жёсткого предела, заданного параметром компиляции SQLITE_MAX_MMAP_SIZE, или жёсткого предела, заданного во время запуска вторым аргументом sqlite3_config(SQLITE_CONFIG_MMAP_SIZE).

Размер области ввода-вывода с отображением в память нельзя изменить, пока эта область активно используется, чтобы не отменить отображение памяти, необходимой выполняющимся инструкциям SQL. По этой причине прагма mmap_size может не выполнить никаких действий, если предыдущее значение mmap_size было ненулевым и в это же время на том же подключении к базе данных выполняются другие инструкции SQL.

PRAGMA module_list;

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

PRAGMA optimize;
PRAGMA optimize(MASK);
PRAGMA schema.optimize;
PRAGMA schema.optimize(MASK);

Пытается оптимизировать базу данных. В первых двух формах оптимизируются все схемы, а в двух последних — только указанная схема.

В большинстве приложений использование PRAGMA optimize следующим образом поможет SQLite добиться максимально возможной производительности запросов:

1. Приложениям, использующим кратковременные подключения к базе данных, следует выполнять "PRAGMA optimize;" непосредственно перед закрытием каждого подключения к базе данных.

2. Приложениям, использующим долгоживущие подключения к базе данных, следует выполнять "PRAGMA optimize=0x10002;" при первом открытии подключения, а затем периодически выполнять "PRAGMA optimize;", например раз в день или раз в час.

3. Всем приложениям следует выполнять "PRAGMA optimize;" после изменения схемы, особенно после одной или нескольких инструкций CREATE INDEX.

Обычно эта прагма не выполняет никаких действий или выполняет их в минимальном объёме и работает очень быстро. Если требуется выполнить ANALYZE для одной или нескольких таблиц, прагма задаёт временный предел анализа, действующий только во время выполнения этой прагмы и не позволяющий вызовам ANALYZE выполняться слишком долго.

Рекомендуется, чтобы приложения с кратковременными подключениями к базе данных выполняли "PRAGMA optimize" один раз при закрытии подключения. Приложениям с долгоживущими подключениями к базе данных следует выполнять "PRAGMA optimize=0x10002" при первом открытии подключения, а затем снова выполнять "PRAGMA optimize" с периодическими интервалами — например, раз в день. Всем приложениям следует выполнять "PRAGMA optimize" после изменений схемы, особенно после CREATE INDEX.

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

Необязательный аргумент MASK — это битовая маска оптимизаций, которые нужно выполнить:

Значение MASK по умолчанию — 0xfffe.

Чтобы просмотреть все оптимизации, которые были бы выполнены, не выполняя их на самом деле, запустите "PRAGMA optimize(-1)".

Определение момента выполнения Analyze

В текущей реализации анализ таблицы выполняется тогда и только тогда, когда истинны все следующие условия:

1. Установлен бит 0x02 маски MASK.
2. Таблица является обычной, а не представлением или виртуальной таблицей.
3. Имя таблицы не начинается с "sqlite_".
4. Истинно одно или несколько из следующих условий:
   1. Установлен бит 0x10000 маски MASK.
   2. В таблице sqlite_stat1 отсутствуют записи для одного или нескольких индексов таблицы.
   3. Планировщик запросов в какой-либо момент существования текущего подключения к базе данных использовал статистику sqlite_stat1 для одного или нескольких индексов этой таблицы.
5. Истинно одно или несколько из следующих условий:
   1. В таблице sqlite_stat1 отсутствуют записи для одного или нескольких индексов таблицы.
   2. Число строк в таблице с момента последнего выполнения ANALYZE для этой таблицы увеличилось или уменьшилось в 10 и более раз.

Правила определения того, когда следует анализировать таблицы, вероятно, изменятся в будущих выпусках. В будущем могут появиться новые значения MASK. В будущих версиях этой PRAGMA вместо битовой маски может приниматься строковый литерал, однако аргумент в виде битовой маски продолжит поддерживаться для обратной совместимости.

PRAGMA schema.page_count;

Возвращает общее число страниц в файле базы данных.

PRAGMA schema.page_size;
PRAGMA schema.page_size = bytes;

Получает или задаёт размер страницы базы данных. Размер страницы должен быть степенью двойки в диапазоне от 512 до 65536 включительно.

При создании новой базы данных SQLite назначает ей размер страницы с учётом платформы и файловой системы. На протяжении многих лет размер страницы по умолчанию почти всегда составлял 1024 байта, но начиная с SQLite версии 3.12.0 (2016-03-29) размер страницы по умолчанию увеличился до 4096 байт. Для большинства приложений рекомендуется использовать размер страницы по умолчанию.

Указание нового размера страницы не приводит к его немедленному изменению. Вместо этого новый размер запоминается и применяется при создании базы данных, если она ещё не существует на момент выполнения PRAGMA page_size, либо при следующей команде VACUUM, выполненной для того же подключения к базе данных вне режима WAL.

Параметр компиляции SQLITE_DEFAULT_PAGE_SIZE можно использовать, чтобы изменить размер страницы по умолчанию, назначаемый новым базам данных.

PRAGMA parser_trace = boolean;

Если SQLite была скомпилирована с параметром компиляции SQLITE_DEBUG, то PRAGMA parser_trace можно использовать для включения трассировки синтаксического анализатора SQL, используемого внутри SQLite. Эта возможность предназначена для отладки самой SQLite.

Эта PRAGMA предназначена для отладки самой SQLite. Она доступна только при использовании параметра компиляции SQLITE_DEBUG.

PRAGMA pragma_list;

Эта PRAGMA возвращает список команд PRAGMA, известных подключению к базе данных.

PRAGMA query_only;
PRAGMA query_only = boolean;

Если PRAGMA query_only включена, она запрещает изменять данные в файлах базы данных. При включённой PRAGMA любая попытка выполнить CREATE, DELETE, DROP, INSERT или UPDATE приведёт к ошибке SQLITE_READONLY. Однако база данных не становится по-настоящему доступной только для чтения. По-прежнему можно выполнить контрольную точку или COMMIT, а возвращаемое значение функции sqlite3_db_readonly() не изменяется.

PRAGMA schema.quick_check;
PRAGMA schema.quick_check(N)
PRAGMA schema.quick_check(TABLENAME)

Эта PRAGMA подобна integrity_check, за исключением того, что она не проверяет ограничения UNIQUE и соответствие содержимого индексов содержимому таблиц. Пропуская проверку UNIQUE и согласованности индексов, quick_check выполняется быстрее. PRAGMA quick_check выполняется за время O(N), тогда как PRAGMA integrity_check требует времени O(NlogN), где N — общее число строк в базе данных. В остальном эти две PRAGMA одинаковы.

PRAGMA read_uncommitted;
PRAGMA read_uncommitted = boolean;

Получает, задаёт или сбрасывает уровень изоляции READ UNCOMMITTED. Уровень изоляции SQLite по умолчанию — SERIALIZABLE. Любой процесс или поток может выбрать изоляцию READ UNCOMMITTED, но уровень SERIALIZABLE всё равно будет использоваться, за исключением подключений, совместно использующих кэш страниц и схемы. Совместное использование кэша включается с помощью API sqlite3_enable_shared_cache(). По умолчанию совместное использование кэша выключено.

Дополнительную информацию см. в разделе Режим общего кэша SQLite.

PRAGMA recursive_triggers;
PRAGMA recursive_triggers = boolean;

Получает, задаёт или сбрасывает возможность рекурсивного вызова триггеров.

Изменение значения recursive_triggers влияет на выполнение всех операторов, подготовленных с использованием подключения к базе данных, в том числе подготовленных до изменения этого параметра. Любые существующие операторы, подготовленные с помощью устаревшего интерфейса sqlite3_prepare(), после изменения значения recursive_triggers могут завершиться ошибкой SQLITE_SCHEMA.

До SQLite версии 3.6.18 (2009-09-11) рекурсивные триггеры не поддерживались. SQLite всегда работала так, как если бы эта PRAGMA была установлена в OFF. Поддержка рекурсивных триггеров была добавлена в версии 3.6.18, но из соображений совместимости изначально была выключена по умолчанию. В будущих версиях SQLite рекурсивные триггеры могут быть включены по умолчанию.

Максимальная глубина рекурсии триггеров ограничена значением, заданным параметром компиляции SQLITE_MAX_TRIGGER_DEPTH, а также ограничением времени выполнения, заданным вызовом sqlite3_limit(db,SQLITE_LIMIT_TRIGGER_DEPTH,...).

PRAGMA reverse_unordered_selects;
PRAGMA reverse_unordered_selects = boolean;

Если эта PRAGMA включена, многие операторы SELECT без предложения ORDER BY выдают результаты в обратном порядке по сравнению с обычным. Это может помочь отладить приложения, которые делают неверные предположения о порядке результатов. PRAGMA reverse_unordered_selects работает для большинства операторов SELECT, однако планировщик запросов иногда может выбрать алгоритм, который нелегко обратить; в этом случае результаты будут выводиться в одном и том же порядке независимо от настройки reverse_unordered_selects.

SQLite не гарантирует порядок результатов, если в операторе SELECT отсутствует предложение ORDER BY. Тем не менее порядок результатов не меняется от запуска к запуску, поэтому многие приложения ошибочно начинают полагаться на произвольный порядок вывода, каким бы он ни был. Однако в новых версиях SQLite иногда появляются улучшения оптимизатора, из-за которых порядок вывода запросов без предложений ORDER BY может измениться. В таких случаях приложения, зависящие от определённого порядка вывода, могут работать неправильно. Если несколько раз запустить приложение с этой PRAGMA как выключенной, так и включённой, можно выявить и заранее исправить случаи, когда приложение делает ошибочные предположения о порядке вывода, что позволит уменьшить количество проблем, вызванных компоновкой с другой версией SQLite.

PRAGMA schema.schema_version;
PRAGMA schema.schema_version = integer ;

PRAGMA schema_version получает или задаёт значение целого числа версии схемы по смещению 40 в заголовке базы данных.

SQLite автоматически увеличивает версию схемы при каждом её изменении. При выполнении каждого оператора SQL проверяется версия схемы, чтобы убедиться, что схема не изменилась с момента подготовки оператора SQL. Нарушение этого механизма с помощью "PRAGMA schema_version=N" для изменения значения schema_version может привести к выполнению оператора SQL с использованием устаревшей схемы, что может повлечь за собой неверные результаты и/или повреждение базы данных. Читать schema_version всегда безопасно, но изменение этого значения может вызвать проблемы. Поэтому попытки изменить значение schema_version молча игнорируются, если для подключения к базе данных включён защитный режим.

Предупреждение: Неправильное использование этой PRAGMA может привести к повреждению базы данных.

Для целей этой PRAGMA команда VACUUM считается изменением схемы, поскольку VACUUM обычно изменяет значения "rootpage" для записей в таблице sqlite_schema.

См. также PRAGMA application_id и PRAGMA user_version.

PRAGMA schema.secure_delete;
PRAGMA schema.secure_delete = boolean|FAST

Запрос или изменение настройки безопасного удаления. Если secure_delete включена, SQLite перезаписывает удалённые данные нулями. Значение по умолчанию для secure_delete определяется параметром компиляции SQLITE_SECURE_DELETE и обычно равно off. Настройка off повышает производительность secure_delete, сокращая количество тактов процессора и объём операций ввода-вывода на диске. Приложениям, которые хотят избежать сохранения следов, пригодных для криминалистического анализа, после удаления или обновления данных, следует включить PRAGMA secure_delete перед удалением или обновлением либо выполнить VACUUM после удаления или обновления.

Настройка "fast" для secure_delete (добавлена примерно 2017-08-01) представляет собой промежуточный режим между "on" и "off". Если для secure_delete задано значение "fast", SQLite перезаписывает удалённые данные нулями только в том случае, если это не увеличивает объём операций ввода-вывода. Иными словами, настройка "fast" использует больше тактов процессора, но не увеличивает объём операций ввода-вывода. В результате старые данные удаляются со страниц b-дерева, но на страницах свободного списка могут оставаться следы, пригодные для криминалистического анализа.

Если есть подключённые базы данных, а в PRAGMA не указана база данных, настройка secure-delete изменяется для всех баз данных. Для вновь подключаемых баз данных настройка secure-delete задаётся значением основной базы данных на момент вычисления команды ATTACH.

Если несколько подключений к базе данных используют один и тот же кэш, изменение флага secure-delete в одном подключении к базе данных изменяет его для всех подключений.

Ограничение: PRAGMA secure_delete удаляет данные только из обычных таблиц. Если виртуальные таблицы хранят данные в теневых таблицах, удаление данных из виртуальной таблицы не обязательно удалит следы из теневых таблиц. В частности, виртуальные таблицы FTS3 и FTS5, входящие в состав SQLite, могут оставлять следы в своих теневых таблицах, даже если включена PRAGMA secure_delete.

PRAGMA short_column_names;
PRAGMA short_column_names = boolean;

Запрос или изменение флага коротких имён столбцов. Этот флаг влияет на способ, которым SQLite присваивает имена столбцам данных, возвращаемым операторами SELECT. Подробности см. в PRAGMA full_column_names.

Эта PRAGMA устарела и сохранена только для обратной совместимости. В новых приложениях не следует использовать эту PRAGMA. В старых приложениях следует отказаться от её использования при первой возможности. Эту PRAGMA можно исключить из сборки, если SQLite скомпилирован с параметром SQLITE_OMIT_DEPRECATED.

PRAGMA shrink_memory

Эта PRAGMA заставляет подключение к базе данных, для которого она вызвана, освободить как можно больше памяти, вызывая sqlite3_db_release_memory().

PRAGMA soft_heap_limit
PRAGMA soft_heap_limit=N

Эта PRAGMA вызывает интерфейс sqlite3_soft_heap_limit64() с аргументом N, если он указан и является неотрицательным целым числом. PRAGMA soft_heap_limit всегда возвращает то же целое число, которое возвращает функция sqlite3_soft_heap_limit64(-1) на языке C.

См. также PRAGMA hard_heap_limit.

PRAGMA stats;

Эта PRAGMA возвращает вспомогательную информацию о таблицах и индексах. Возвращаемая информация используется при тестировании, чтобы помочь проверить правильность работы планировщика запросов. Формат и значение этой PRAGMA, вероятно, будут меняться от выпуска к выпуску. В связи с нестабильностью её поведения и формата вывода описание этой PRAGMA намеренно не документируется.

Эта PRAGMA предназначена только для тестирования и проверки SQLite. Её поведение может измениться без предварительного уведомления, поэтому её не рекомендуется использовать в приложениях.

PRAGMA schema.synchronous;
PRAGMA schema.synchronous = 0 | OFF | 1 | NORMAL | 2 | FULL | 3 | EXTRA;

Запрос или изменение настройки флага «synchronous». Первая форма (запрос) возвращает настройку synchronous в виде целого числа. Вторая форма изменяет настройку synchronous. Значения различных настроек synchronous описаны ниже:

EXTRA (3)

Режим synchronous EXTRA похож на FULL, но дополнительно каталог, содержащий журнал отката, синхронизируется после удаления этого журнала для фиксации транзакции в режиме DELETE. EXTRA обеспечивает дополнительную надёжность, если вскоре после фиксации происходит отключение питания. Без EXTRA, в зависимости от используемой файловой системы, одна транзакция, зафиксированная непосредственно перед отключением питания, может быть отменена после перезагрузки. База данных не будет повреждена. Но последняя транзакция может быть потеряна, что нарушит надёжность, если не задан режим EXTRA.

В режиме WAL EXTRA ничем не отличается от FULL.

FULL (2)

Если synchronous имеет значение FULL (2), движок базы данных SQLite использует метод xSync из VFS, чтобы убедиться, что всё содержимое надёжно записано на диск, прежде чем продолжить работу. Это гарантирует, что сбой операционной системы или отключение питания не приведут к повреждению базы данных.

FULL — это режим synchronous по умолчанию для журнала отката. В режиме WAL FULL обеспечивает атомарность, согласованность, изоляцию и долговечность (ACID), а с журналом отката — атомарность, согласованность и изоляцию. При использовании журнала отката FULL также может обеспечивать долговечность — в зависимости от используемой файловой системы. В режиме отката FULL не обязательно обеспечивает долговечность при отключении питания, поэтому, если важна долговечность, лучше установить режим synchronous в EXTRA.

NORMAL (1)

Если synchronous имеет значение NORMAL (1), движок базы данных SQLite по-прежнему выполняет синхронизацию в наиболее критические моменты, но реже, чем в режиме FULL. Существует очень небольшая (но ненулевая) вероятность, что отключение питания в самый неподходящий момент повредит базу данных при journal_mode=DELETE на старой файловой системе. Режим WAL защищён от повреждения при synchronous=NORMAL, а режим DELETE, вероятно, также безопасен на современных файловых системах. Режим WAL всегда обеспечивает согласованность при synchronous=NORMAL, но при этом не гарантирует долговечность. Транзакция, зафиксированная в режиме WAL при synchronous=NORMAL, может быть отменена после отключения питания или сбоя системы. Транзакции сохраняются при сбоях приложения независимо от настройки synchronous или режима журнала.

Настройка synchronous=NORMAL обеспечивает оптимальный баланс между производительностью и безопасностью для большинства приложений, работающих в режиме WAL. В режиме WAL при synchronous=NORMAL долговечность при отключении питания не гарантируется, но для большинства приложений это не имеет значения. Транзакции по-прежнему атомарны, согласованы и изолированы — это наиболее важные свойства для большинства вариантов использования.

OFF (0)

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

Настройка synchronous в OFF — хороший вариант при создании новой базы данных с нуля, если процесс её создания можно повторить в случае отключения питания в ходе работы и производительность критически важна.

Вот таблица:

В режиме WAL, когда synchronous имеет значение NORMAL (1), файл WAL синхронизируется перед каждой контрольной точкой, а файл базы данных синхронизируется после каждой завершённой контрольной точки. Заголовок файла WAL синхронизируется, когда файл WAL начинает использоваться повторно после контрольной точки, но в ходе большинства транзакций операции синхронизации не выполняются. При synchronous=FULL в режиме WAL после фиксации каждой транзакции выполняется дополнительная синхронизация файла WAL. Дополнительная синхронизация WAL после каждой транзакции помогает обеспечить сохранность транзакций при отключении питания. Транзакции остаются согласованными как с дополнительной синхронизацией, выполняемой при synchronous=FULL, так и без неё. Если долговечность не имеет значения, в режиме WAL обычно достаточно synchronous=NORMAL.

Для схемы TEMP всегда используется synchronous=OFF, поскольку содержимое TEMP временное и не должно сохраняться при отключении питания. Попытки изменить настройку synchronous для TEMP молча игнорируются.

См. также прагмы fullfsync и checkpoint_fullfsync.

PRAGMA schema.table_info(table-name);

Эта прагма возвращает по одной строке для каждого обычного столбца указанной таблицы. Результирующий набор включает следующие столбцы: "name" (имя); "type" (тип данных, если указан, иначе ''); "notnull" (может ли столбец содержать NULL); "dflt_value" (значение по умолчанию для столбца); и "pk" (ноль для столбцов, не входящих в первичный ключ, либо индекс столбца в первичном ключе, начинающийся с 1).

Не следует придавать столбцу "cid" значение, выходящее за рамки «порядкового номера в текущем результирующем наборе».

В качестве таблицы, указанной в прагме table_info, также может выступать представление.

Эта прагма не отображает сведения о генерируемых столбцах или скрытых столбцах. Используйте PRAGMA table_xinfo, чтобы получить более полный список столбцов, включающий генерируемые и скрытые столбцы.

PRAGMA table_list;
PRAGMA schema.table_list;
PRAGMA table_list(table-name);

Эта прагма возвращает сведения о таблицах и представлениях в схеме: одна таблица на строку результата. Прагма table_list впервые появилась в SQLite версии 3.37.0 (2021-11-27). В первоначальном выпуске прагма table_list возвращает столбцы, перечисленные ниже. В будущих версиях SQLite, вероятно, появятся дополнительные столбцы результата.

1. schema: схема, в которой находится таблица или представление (например, "main" или "temp").
2. name: имя таблицы или представления.
3. type: тип объекта — один из следующих: "table", "view", "shadow" (для теневых таблиц) или "virtual" для виртуальных таблиц.
4. ncol: количество столбцов в таблице, включая генерируемые столбцы и скрытые столбцы.
5. wr: 1, если таблица является таблицей WITHOUT ROWID, или 0 в противном случае.
6. strict: 1, если таблица является таблицей STRICT, или 0 в противном случае.
7. В будущих выпусках, вероятно, будут добавлены дополнительные столбцы.

По умолчанию отображаются все таблицы во всех схемах. Если перед прагмой указано имя schema., отображаются только таблицы из этой схемы. Если указан аргумент table-name, возвращаются сведения только об этой таблице.

PRAGMA schema.table_xinfo(table-name);

Эта прагма возвращает по одной строке для каждого столбца в указанной таблице, включая генерируемые столбцы и скрытые столбцы. Результат содержит те же столбцы, что и PRAGMA table_info, а также столбец "hidden", значение которого обозначает обычный столбец (0), динамический или хранимый генерируемый столбец (2 или 3) либо скрытый столбец виртуальной таблицы (1). Строки, для которых значение этого поля отлично от нуля, не включаются в результат PRAGMA table_info.

PRAGMA temp_store;
PRAGMA temp_store = 0 | DEFAULT | 1 | FILE | 2 | MEMORY;

Запрашивает или изменяет значение параметра "temp_store". Если temp_store имеет значение DEFAULT (0), для определения места хранения временных таблиц и индексов используется макрос препроцессора C SQLITE_TEMP_STORE, заданный при компиляции. Если temp_store имеет значение MEMORY (2), временные таблицы и индексы хранятся так же, как в чисто базах данных в памяти. Если temp_store имеет значение FILE (1), временные таблицы и индексы хранятся в файле. Прагму temp_store_directory можно использовать, чтобы указать каталог для временных файлов, если задано значение FILE. При изменении значения temp_store все существующие временные таблицы, индексы, триггеры и представления немедленно удаляются.

Настройка этой прагмы может быть переопределена символом препроцессора C SQLITE_TEMP_STORE, заданным при компиляции библиотеки. В следующей таблице показано, как взаимодействуют макрос препроцессора SQLITE_TEMP_STORE и прагма temp_store:

SQLITE_TEMP_STORE	PRAGMA temp_store	Используемое хранилище для временных таблиц и индексов
0	любое	файл
1	0	файл
1	1	файл
1	2	память
2	0	память
2	1	файл
2	2	память
3	любое	память

PRAGMA temp_store_directory;
PRAGMA temp_store_directory = 'directory-name';

Запрашивает или изменяет значение глобальной переменной sqlite3_temp_directory, которую многие серверные компоненты интерфейса операционной системы используют, чтобы определить место хранения временных таблиц и индексов.

При изменении значения temp_store_directory все существующие временные таблицы, индексы, триггеры и представления в соединении с базой данных, выполнившем прагму, немедленно удаляются. На практике temp_store_directory следует задавать сразу после открытия первого соединения с базой данных в процессе. Если temp_store_directory изменить для одного соединения с базой данных, пока в том же процессе открыты другие соединения, поведение не определено и, вероятно, нежелательно.

Изменение значения temp_store_directory не является потокобезопасным. Не изменяйте значение temp_store_directory, если в это же время другой поток приложения выполняет какой-либо интерфейс SQLite. Это приведёт к неопределённому поведению. При изменении значения temp_store_directory производится запись в глобальную переменную sqlite3_temp_directory, которая не защищена мьютексом.

Значение directory-name следует заключать в одинарные кавычки. Чтобы вернуть каталог по умолчанию, задайте для directory-name пустую строку, например: PRAGMA temp_store_directory = ''. Если каталог directory-name не найден или недоступен для записи, возникает ошибка.

Каталог по умолчанию для временных файлов зависит от операционной системы. Некоторые интерфейсы операционной системы могут игнорировать эту переменную и размещать временные файлы в другом каталоге, отличном от указанного здесь. В этом смысле данная прагма носит лишь рекомендательный характер.

Эта прагма устарела и существует только для обратной совместимости. В новых приложениях не следует использовать эту прагму. В старых приложениях следует прекратить её использование при первой возможности. Эту прагму можно исключить из сборки, если SQLite скомпилирован с параметром SQLITE_OMIT_DEPRECATED.

PRAGMA threads;
PRAGMA threads = N;

Запрашивает или изменяет значение ограничения sqlite3_limit(db,SQLITE_LIMIT_WORKER_THREADS,...) для текущего соединения с базой данных. Это ограничение задаёт верхнюю границу количества вспомогательных потоков, которые подготовленному оператору разрешено запускать для помощи при выполнении запроса. По умолчанию ограничение равно 0, если оно не изменено с помощью параметра компиляции SQLITE_DEFAULT_WORKER_THREADS. Нулевое значение означает, что вспомогательные потоки запускаться не будут.

Эта прагма является тонкой обёрткой над интерфейсом sqlite3_limit(db,SQLITE_LIMIT_WORKER_THREADS,...).

PRAGMA trusted_schema;
PRAGMA trusted_schema = boolean;

Параметр trusted_schema — это логическое значение для каждого соединения, определяющее, разрешено ли представлениям, триггерам или выражениям схемы выполнять не прошедшие аудит безопасности функции SQL и виртуальные таблицы, например в ограничениях CHECK, предложениях DEFAULT, генерируемых столбцах, индексах по выражениям и/или частичных индексах. Этим параметром также можно управлять с помощью интерфейса языка C sqlite3_db_config(db,SQLITE_DBCONFIG_TRUSTED_SCHEMA,...).

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

Параметр компиляции -DSQLITE_TRUSTED_SCHEMA=0 задаёт для этого параметра значение OFF по умолчанию.

PRAGMA schema.user_version;
PRAGMA schema.user_version = integer ;

Прагма user_version позволяет получить или задать значение целого числа версии пользователя со смещением 60 в заголовке базы данных. Версия пользователя — это целое число, которое приложения могут использовать по своему усмотрению. SQLite самостоятельно не использует значение версии пользователя.

См. также прагму application_id и прагму schema_version.

PRAGMA vdbe_addoptrace = boolean;

Если SQLite был скомпилирован с параметром компиляции SQLITE_DEBUG, то pragma vdbe_addoptrace можно использовать для отображения полных кодов операций VDBE по мере их создания при генерации кода. Эта возможность используется для отладки самого SQLite. Дополнительные сведения см. в документации по VDBE.

Эта pragma предназначена для отладки самого SQLite. Она доступна только при использовании параметра компиляции SQLITE_DEBUG.

PRAGMA vdbe_debug = boolean;

Если SQLite был скомпилирован с параметром компиляции SQLITE_DEBUG, то pragma vdbe_debug является сокращённой записью для трёх других pragma, предназначенных только для отладки: vdbe_addoptrace, vdbe_listing и vdbe_trace. Эта возможность используется для отладки самого SQLite. Дополнительные сведения см. в документации по VDBE.

Эта pragma предназначена для отладки самого SQLite. Она доступна только при использовании параметра компиляции SQLITE_DEBUG.

PRAGMA vdbe_listing = boolean;

Если SQLite был скомпилирован с параметром компиляции SQLITE_DEBUG, то pragma vdbe_listing можно использовать для вывода полного списка кодов операций виртуальной машины в стандартный поток вывода при вычислении каждого оператора. Когда vdbe_listing включена, всё содержимое программы выводится непосредственно перед началом её выполнения. После вывода списка оператор выполняется обычным образом. Эта возможность используется для отладки самого SQLite. Дополнительные сведения см. в документации по VDBE.

Эта pragma предназначена для отладки самого SQLite. Она доступна только при использовании параметра компиляции SQLITE_DEBUG.

PRAGMA vdbe_trace = boolean;

Если SQLite был скомпилирован с параметром компиляции SQLITE_DEBUG, то pragma vdbe_trace можно использовать для вывода кодов операций виртуальной машины в стандартный поток вывода по мере их вычисления. Эта возможность используется для отладки SQLite. Дополнительные сведения см. в документации по VDBE.

Эта pragma предназначена для отладки самого SQLite. Она доступна только при использовании параметра компиляции SQLITE_DEBUG.

PRAGMA wal_autocheckpoint;
PRAGMA wal_autocheckpoint=N;

Эта pragma запрашивает или задаёт интервал автоматической контрольной точки для журнала предварительной записи. Когда включён журнал предварительной записи (с помощью pragma journal_mode), контрольная точка будет автоматически запускаться, когда размер журнала предварительной записи достигнет или превысит N страниц. Установка размера автоматической контрольной точки в ноль или отрицательное значение отключает автоматическое создание контрольных точек.

Эта pragma является оболочкой для интерфейса C sqlite3_wal_autocheckpoint(). Все автоматические контрольные точки имеют режим PASSIVE.

По умолчанию автоматическое создание контрольных точек включено с интервалом 1000 или SQLITE_DEFAULT_WAL_AUTOCHECKPOINT.

PRAGMA schema.wal_checkpoint;
PRAGMA schema.wal_checkpoint(PASSIVE);
PRAGMA schema.wal_checkpoint(FULL);
PRAGMA schema.wal_checkpoint(RESTART);
PRAGMA schema.wal_checkpoint(TRUNCATE);
PRAGMA schema.wal_checkpoint(NOOP);

Если включён журнал предварительной записи (с помощью pragma journal_mode), эта pragma запускает операцию контрольной точки для базы данных database или для всех присоединённых баз данных, если database не указана. Если режим журнала предварительной записи отключён, эта pragma ничего не делает и не вызывает ошибок.

Вызов этой pragma без аргумента эквивалентен вызову интерфейса C sqlite3_wal_checkpoint().

PASSIVE

Создаёт контрольную точку для максимально возможного числа кадров, не ожидая завершения работы каких-либо читателей или писателей базы данных. Синхронизирует файл базы данных, если в журнале обработаны все кадры. Этот режим соответствует вызову интерфейса C sqlite3_wal_checkpoint(). В этом режиме функция обратного вызова обработчика занятости никогда не вызывается.

FULL

Этот режим блокирует выполнение (вызывая функцию обратного вызова обработчика занятости) до тех пор, пока не останется писателей базы данных и все читатели не будут читать из последнего снимка базы данных. Затем он создаёт контрольную точку для всех кадров в файле журнала и синхронизирует файл базы данных. Во время работы FULL блокирует параллельную запись, но чтение может продолжаться.

RESTART

Этот режим работает так же, как FULL, но после создания контрольной точки для файла журнала он блокирует выполнение (вызывая функцию обратного вызова обработчика занятости) до тех пор, пока все читатели не закончат работу с файлом журнала. Это гарантирует, что следующий клиент, который будет записывать данные в файл базы данных, начнёт журнал с самого начала. Во время работы RESTART блокирует параллельную запись, но позволяет продолжать чтение.

TRUNCATE

Этот режим работает так же, как RESTART, но после успешного завершения файл WAL усекается до нулевого размера.

NOOP

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

Pragma wal_checkpoint возвращает одну строку с тремя целочисленными столбцами. Первый столбец обычно равен 0, но будет равен 1, если контрольная точка в режиме RESTART, FULL или TRUNCATE не смогла завершиться, например, потому что другая нить или процесс активно использовали базу данных. Иными словами, первый столбец равен 0, если эквивалентный вызов sqlite3_wal_checkpoint_v2() вернул бы SQLITE_OK, или 1, если эквивалентный вызов вернул бы SQLITE_BUSY. Второй столбец содержит количество изменённых страниц, записанных в файл журнала предварительной записи. Третий столбец содержит количество страниц из файла журнала предварительной записи, которые по завершении контрольной точки были успешно перенесены обратно в файл базы данных. Второй и третий столбцы равны -1, если журнала предварительной записи нет, например, когда эта pragma вызвана для соединения с базой данных, работающего не в режиме WAL.

PRAGMA writable_schema = boolean;
PRAGMA writable_schema = RESET

Когда эта pragma включена, а флаг SQLITE_DBCONFIG_DEFENSIVE выключен, таблицу sqlite_schema можно изменять с помощью обычных операторов UPDATE, INSERT и DELETE. Если аргументом является "RESET", запись в схему отключается (как при "PRAGMA writable_schema=OFF"), и, кроме того, схема загружается заново. Предупреждение: неправильное использование этой pragma может легко привести к повреждению файла базы данных.

Последнее обновление этой страницы: 2025-11-13 07:12:58Z