Интерфейс C/C++ для SQLite Version 3

Эта страница предназначается, чтобы быть точной и подробной спецификацией. Для учебного введения посмотрите вместо этого:

• SQLite за 3 минуты или быстрее и/или
• the Введение в интерфейс SQLite C/C++.

Экспериментальные и устаревшие интерфейсы

Интерфейсы SQLite могут быть подразделены на три категории:

1. Стабильные
2. Экспериментальные
3. Устаревшие

Стабильные интерфейсы будут сохраняться неопределенно долго. Применение, которое использует только стабильные интерфейсы, должно всегда быть в состоянии связаться с более новой версии SQLite без любых изменений.

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

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

Ключевые пункты:

• Экспериментальные интерфейсы подвержены изменениям и/или удалению в любое время.
• Устаревшие интерфейсы не должны использоваться в новом коде и могли бы быть демонтированы в некотором будущем выпуске.

Перечень объектов:

Список констант:

Также есть список кодов ошибок

Список функций:

Примечание: Функции, отмеченные "(exp)", экспериментальные, а функции, имена которых зачеркнуты, устаревшие.

Виртуальные флаги сканирования таблицы

#define SQLITE_INDEX_SCAN_UNIQUE      1     /* Scan visits at most 1 row */

Виртуальным внедрениям таблицы позволяют установить поле sqlite3_index_info.idxFlags в некоторую комбинацию этих битов.

Флаги sqlite3_serialize

#define SQLITE_SERIALIZE_NOCOPY 0x001   /* Do no memory allocations */

Ноль или больше следующих констант могут быть OR вместе для аргумента F в sqlite3_serialize(D,S,P,F).

SQLITE_SERIALIZE_NOCOPY значит, что sqlite3_serialize() возвратит указатель на смежную базу данных в памяти, которую это в настоящее время использует, не делая копию базы данных. Если SQLite в настоящее время не использует смежную базу данных в памяти, то этот выбор заставляет sqlite3_serialize() вернуть NULL. SQLite будет использовать смежную базу данных в памяти только, если она была инициализирована предшествующим вызовом sqlite3_deserialize().

Максимум индекса xShmLock

#define SQLITE_SHM_NLOCK        8

Метод xShmLock в sqlite3_io_methods может использовать значения от 0 до этой верхней границей как ее "offset". Ядро SQLite никогда не будет пытаться приобрести или снять блокировку за пределами этого диапазона.

Загружаемый дополнительный Thunk

typedef struct sqlite3_api_routines sqlite3_api_routines;

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

Резервный объект онлайн

typedef struct sqlite3_backup sqlite3_backup;

Записи объекта sqlite3_backup указывают информацию о продолжающейся операции резервного копирования онлайн. Объект sqlite3_backup создается вызовом sqlite3_backup_init() и разрушается вызовом sqlite3_backup_finish().

Объект контекста функции SQL

typedef struct sqlite3_context sqlite3_context;

Контекст, в котором функция SQL выполняется, сохранен в объекте sqlite3_context. Указатель на объект sqlite3_context всегда первый параметр определенным применением функциям SQL. Определенная применением реализация функции SQL передаст этот указатель в вызове sqlite3_result(), sqlite3_aggregate_context(), sqlite3_user_data(), sqlite3_context_db_handle(), sqlite3_get_auxdata() и/или sqlite3_set_auxdata().

26 методов, использующих этот объект:

Название файлов базы данных

SQLITE_EXTERN char *sqlite3_data_directory;

Если эта глобальная переменная будет указывать на последовательность, которая является названием каталога), то все файлы базы данных, определенные с относительным путем и созданные или полученные SQLite, используя встроенные VFS будут расположены относительно того каталога. Если эта переменная NULL, SQLite предполагает, что все файлы базы данных определены с относительным путем, относительно текущего каталога для процесса. Только windows VFS использует эту глобальную переменную, это проигнорировано Unix VFS.

Изменение этой переменной, в то время как соединение с базой данных открыто, может привести к поврежденной базе данных.

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

Прагма data_store_directory может изменить эту переменную и заставить ее указывать на память, полученную из sqlite3_malloc. Кроме того, прагма data_store_directory всегда предполагает, что любая последовательность, на которую указывает эта переменная, проводится в памяти, полученной из sqlite3_malloc и прагма может попытаться освободить эту память, используя sqlite3_free. Следовательно, если эта переменная изменяется непосредственно, это должно быть сделано NULL или указать на память, полученную из sqlite3_malloc, иначе использования прагмы data_store_directory pragma нужно избежать.

Интерфейс OS открытия дескриптора файла

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

Объект sqlite3_file представляет открытый файл в слое интерфейса OS. Отдельные внедрения интерфейса OS захотят подклассифицировать этот объект, прилагая дополнительные области для их собственного использования. pMethods это указатель на объект sqlite3_io_methods, который определяет методы для выполнения операций I/O на открытом файле.

Имя файла

typedef const char *sqlite3_filename;

Тип sqlite3_filename используется SQLite, чтобы передать имена файлов методу xOpen VFS. Это можно привести к (const char*) и рассматривать как нормальный, nul-законченный, буфер UTF-8, содержащий имя файла, но можно также передать к специальному API:

• sqlite3_filename_database()
• sqlite3_filename_journal()
• sqlite3_filename_wal()
• sqlite3_uri_parameter()
• sqlite3_uri_boolean()
• sqlite3_uri_int64()
• sqlite3_uri_key()

Виртуальная таблица информации индекса

struct sqlite3_index_info {
  /* Inputs */
  int nConstraint;           /* Number of entries in aConstraint */
  struct sqlite3_index_constraint {
     int iColumn;              /* Column constrained.  -1 for ROWID */
     unsigned char op;         /* Constraint operator */
     unsigned char usable;     /* True if this constraint is usable */
     int iTermOffset;          /* Used internally - xBestIndex should ignore */
  } *aConstraint;            /* Table of WHERE clause constraints */
  int nOrderBy;              /* Number of terms in the ORDER BY clause */
  struct sqlite3_index_orderby {
     int iColumn;              /* Column number */
     unsigned char desc;       /* True for DESC.  False for ASC. */
  } *aOrderBy;               /* The ORDER BY clause */
  /* Outputs */
  struct sqlite3_index_constraint_usage {
    int argvIndex;           /* if >0, constraint is part of argv to xFilter */
    unsigned char omit;      /* Do not code a test for this constraint */
  } *aConstraintUsage;
  int idxNum;                /* Number used to identify the index */
  char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
  int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
  int orderByConsumed;       /* True if output is already ordered */
  double estimatedCost;           /* Estimated cost of using this index */
  /* Fields below are only available in SQLite 3.8.2 and later */
  sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */
  /* Fields below are only available in SQLite 3.9.0 and later */
  int idxFlags;              /* Mask of SQLITE_INDEX_SCAN_* flags */
  /* Fields below are only available in SQLite 3.10.0 and later */
  sqlite3_uint64 colUsed;    /* Input: Mask of columns used by statement */
};

Структура sqlite3_index_info и ее подструктуры используются в качестве части интерфейса виртуальной таблицы, чтобы передать информацию и получить ответ от метода xBestIndex модуля виртуальной таблицы. Области под **Inputs** это ввод для xBestIndex, они read-only. xBestIndex вставляет свои результаты в поля **Outputs**.

Массив aConstraint[] делает запись ограничений оператора WHERE:

column OP expr

здесь OP это =, <, <=, > или >=. Конкретный оператор сохранен в aConstraint[].op с использованием одного из значений SQLITE_INDEX_CONSTRAINT_. Индекс колонки сохранен в aConstraint[].iColumn. aConstraint[].usable = TRUE, если expr на правой стороне может быть оценен (и таким образом ограничение применимое) и false, если это не так.

Оптимизатор автоматически инвертирует условия формы "expr OP column" и делает другие упрощения в операторе WHERE в попытке получить как можно больше условий оператора WHERE в форму, показанную выше. Массив aConstraint[] выстраивают только условия оператора WHERE, которые относятся к конкретной запрашиваемой виртуальной таблице.

Информация о пункте ORDER BY хранится в aOrderBy []. Каждый термин aOrderBy делает запись колонки пункта ORDER BY.

Поле colUsed указывает, какие колонки виртуальной таблицы могут требоваться текущим просмотром. Виртуальные столбцы таблицы пронумерованы с нуля в порядке в котором они появляются в рамках CREATE TABLE, переданным в sqlite3_declare_vtab(). Для первых 63 колонок (колонки 0-62) соответствующий бит установлен в маске colUsed, если колонка может требоваться SQLite. Если у таблицы есть по крайней мере 64 колонки, и любая колонка направо от первых 63 требуется, то бит 63 в colUsed также установлен. Другими словами, колонка iCol может требоваться, если выражение (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) оценивается к значению, отличному от нуля.

Метод xBestIndex должен заполнять aConstraintUsage[] информацией о том, какие параметры передать xFilter. Если argvIndex>0, тогда правая сторона соответствующего aConstraint[] оценена и становится записью argvIndex в argv. Если aConstraintUsage[].omit = true, то ограничение, как предполагается, полностью обработано виртуальной таблицей и не могло бы быть проверено снова байт-кодом. Флаг aConstraintUsage[].omit является намеком оптимизации. Когда флаг omit в его настройке по умолчанию false, ограничение будет всегда проверяться отдельно в байт-коде. Если флаг omit = true, то ограничение может или не может быть проверено в байт-коде. Другими словами, когда omit = true, нет никакой гарантии, что ограничение не будет проверено снова, используя байт-код.

idxNum и idxStr зарегистрированы и переданы в метод xFilter. sqlite3_free() используется, чтобы освободить idxStr если и только если needToFreeIdxStr = true.

orderByConsumed означает, что вывод от xFilter/xNext произойдет в правильном порядке, чтобы удовлетворить пункт ORDER BY так, чтобы никакой отдельный шаг сортировки не требовался.

Значение estimatedCost это оценка стоимости конкретной стратегии. Стоимость N указывает, что стоимость стратегии подобна линейному просмотру таблицы SQLite с N строками. Стоимость log(N) указывает, что расход операции подобен двоичному поиску на уникальной индексируемой области таблицы SQLite с N строками.

Значение estimatedRows это оценка количества строк, которые будут возвращены стратегией.

Метод xBestIndex может произвольно наполнить поле idxFlags маской флагов SQLITE_INDEX_SCAN_*. В настоящее время есть только один такой флаг SQLITE_INDEX_SCAN_UNIQUE. Если метод xBestIndex его установит, SQLite предполагает, что стратегия может посетить самое большее одну строку.

Кроме того, если xBestIndex устанавливает флаг SQLITE_INDEX_SCAN_UNIQUE, то SQLite также предполагает, что, если вызов метода xUpdate() сделан как часть того же самого запроса, чтобы удалить или обновить виртуальную строку таблицы и внедрение возвращает SQLITE_CONSTRAINT, то нет никакой потребности к обратной перемотке никаких изменений базы данных. Другими словами, если xUpdate() вернет SQLITE_CONSTRAINT, содержание базы данных должно быть точно таким, каким было прежде, чем вызвали xUpdate. В отличие от этого, если SQLITE_INDEX_SCAN_UNIQUE не установлен, и xUpdate вернет SQLITE_CONSTRAINT, любые изменения базы данных, внесенные методом xUpdate, автоматически отменены SQLite.

ВАЖНО: поле estimatedRows было добавлено к структуре sqlite3_index_info в SQLite version 3.8.2 (2013-12-06). Если виртуальное расширение таблицы используется с версией SQLite ранее, чем 3.8.2, результаты попытки прочитать или написать поле estimatedRows не определены (но, вероятно, будут включать сбой приложения). Поэтому estimatedRows можно использовать только если sqlite3_libversion_number() возвращает значение больше или равное 3008002. Точно так же поле idxFlags добавлено в version 3.9.0 (2015-10-14). Это может использоваться только, если sqlite3_libversion_number() возвращает значение больше или равное 3009000.

3 метода, использующих этот объект: sqlite3_vtab_collation(), sqlite3_vtab_distinct(), sqlite3_vtab_rhs_value()

Методы объекта файлового интерфейса виртуальной OS

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* Methods above are valid for version 2 */
  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  /* Methods above are valid for version 3 */
  /* Additional methods may be added in future releases */
};

Каждый файл, открытый методом sqlite3_vfs.xOpen, наполняет объект sqlite3_file (или чаще всего подкласс объекта sqlite3_file) указателем на экземпляр этого объекта. Этот объект определяет методы, используемые, чтобы выполнить различные операции для открытого файла, представленного объектом sqlite3_file.

Если метод sqlite3_vfs.xOpen устанавливает элемент sqlite3_file.pMethods в ненулевой указатель, то метод sqlite3_io_methods.xClose может быть вызван, даже если sqlite3_vfs.xOpen сообщил, что это потерпело неудачу. Единственный способ предотвратить вызов xClose после неудавшегося sqlite3_vfs.xOpen это установить sqlite3_file.pMethods = NULL.

Аргумент флагов xSync может быть одним из SQLITE_SYNC_NORMAL или SQLITE_SYNC_FULL. Предпочтительный вариант: обычный fsync(). Второй выбор это стиль Mac OS X fullsync. Флаг SQLITE_SYNC_DATAONLY может быть ORed, чтобы указать, что только данные файла, но не его inode должны синхронизироваться.

Целочисленные значения в xLock() and xUnlock() это одно из:

• SQLITE_LOCK_NONE,
• SQLITE_LOCK_SHARED,
• SQLITE_LOCK_RESERVED,
• SQLITE_LOCK_PENDING или
• SQLITE_LOCK_EXCLUSIVE.

Метод xFileControl() это универсальный интерфейс, который позволяет VFS непосредственно управлять открытым файлом, используя интерфейс sqlite3_file_control(). Второй аргумент "op" это код операции целого числа. Третий аргумент это универсальный указатель, предназначенный, чтобы указать на структуру, которая может содержать аргументы или место, в котором можно написать возвращаемые значения. Потенциальное использование для xFileControl() могло бы быть функциями, чтобы позволить блокировать с перерывами, изменить стратегию захвата (например, чтобы использовать блокировки точечного файла), справиться о статусе или снять блокировки. Ядро SQLite резервирует все коды операции меньше 100 для собственного использования. Список opcodes меньше 100 доступны. Приложения, которые определяют метод xFileControl, должны использовать коды операции больше 100, чтобы избежать конфликтов. Внедрения VFS должны возвратить SQLITE_NOTFOUND для кодов операции контроля за файлом, которые они не распознали.

Метод xSectorSize() возвращает размер сектора устройства, которое хранит файл. Размер сектора это минимум записи, который может быть выполнен, не нарушая другие байты в файле. Метод xDeviceCharacteristics() возвращает битовые векторные описания поведения базового устройства:

• SQLITE_IOCAP_ATOMIC
• SQLITE_IOCAP_ATOMIC512
• SQLITE_IOCAP_ATOMIC1K
• SQLITE_IOCAP_ATOMIC2K
• SQLITE_IOCAP_ATOMIC4K
• SQLITE_IOCAP_ATOMIC8K
• SQLITE_IOCAP_ATOMIC16K
• SQLITE_IOCAP_ATOMIC32K
• SQLITE_IOCAP_ATOMIC64K
• SQLITE_IOCAP_SAFE_APPEND
• SQLITE_IOCAP_SEQUENTIAL
• SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
• SQLITE_IOCAP_POWERSAFE_OVERWRITE
• SQLITE_IOCAP_IMMUTABLE
• SQLITE_IOCAP_BATCH_ATOMIC

SQLITE_IOCAP_ATOMIC означает, что все записи атомные. SQLITE_IOCAP_ATOMICnnn значит, что записи блоков в размере nnn байт и выровнены с адресом, который является целым числом, кратным nnn, атомные. SQLITE_IOCAP_SAFE_APPEND означает, что когда данные добавлены к файлу, данные приложены сначала, потом размер файла расширен, но никогда наоборот. SQLITE_IOCAP_SEQUENTIAL означает, что информация написана диску в том же самом порядке, как вызовы xWrite().

Если xRead() = SQLITE_IOERR_SHORT_READ это должно также заполнить непрочитанные части буфера нолями. VFS, который терпит неудачу при заполнении нулями, вроде бы работает. Но рано или поздно это повредит БД.

Режимы выделения памяти

typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int);         /* Memory allocation function */
  void (*xFree)(void*);          /* Free a prior allocation */
  void *(*xRealloc)(void*,int);  /* Resize an allocation */
  int (*xSize)(void*);           /* Return the size of an allocation */
  int (*xRoundup)(int);          /* Round up request size to allocation size */
  int (*xInit)(void*);           /* Initialize the memory allocator */
  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  void *pAppData;                /* Argument to xInit() and xShutdown() */
};

Экземпляр этого объекта определяет интерфейс между SQLite и режимами выделения памяти низкого уровня.

Этот объект используется только в одном месте в интерфейсе SQLite. Указатель на экземпляр этого объекта это аргумент sqlite3_config() когда параметр конфигурации SQLITE_CONFIG_MALLOC или SQLITE_CONFIG_GETMALLOC. Создавая экземпляр этого объекта и передавая его sqlite3_config( SQLITE_CONFIG_MALLOC) во время конфигурации, приложение может определить альтернативную подсистему выделения памяти для SQLite, чтобы использовать для всех его потребностей в динамической памяти.

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

Методы xMalloc, xRealloc и xFree должны работать как функции malloc(), realloc() и free() стандартной библиотеки C. SQLite гарантирует, что второй аргумент xRealloc всегда значение, возвращенное предшествующим вызовом xRoundup.

xSize должен возвратить ассигнованный размер выделения памяти, ранее полученный из xMalloc или xRealloc. Ассигнованный размер всегда, по крайней мере, столь же большой как требуемый размер, но может быть больше.

xRoundup возвращает то, что было бы ассигнованным размером выделения памяти, учитывая конкретный требуемый размер. Большинство распределителей памяти округляет выделение памяти, по крайней мере, к следующему числу, кратному 8. Некоторые распределители округляют к большему кратному числу или к степени 2. Каждый запрос выделения памяти, входящий через sqlite3_malloc() или sqlite3_realloc(), сначала вызывает xRoundup. Если xRoundup вернет 0, это заставляет соответствующее выделение памяти терпеть неудачу.

xInit инициализирует распределителя памяти. Например, это могло бы ассигновать любой нужный mutex или инициализировать внутренние структуры данных. xShutdown вызван (косвенно) sqlite3_shutdown() и должен освободить любые ресурсы, приобретенные xInit. Указатель pAppData используется в качестве единственного параметра xInit и xShutdown.

SQLite хранит SQLITE_MUTEX_STATIC_MAIN mutex, когда вызывает xInit, таким образом метод xInit не должен быть ориентирован на многопотоковое исполнение. xShutdown вызывают только из sqlite3_shutdown() таким образом, это не должно быть ориентировано на многопотоковое исполнение. Для всех других методов SQLite держит SQLITE_MUTEX_STATIC_MEM mutex пока параметр конфигурации SQLITE_CONFIG_MEMSTATUS включен (это по умолчанию), таким образом методы автоматически преобразовываются в последовательную форму. Однако, если SQLITE_CONFIG_MEMSTATUS отключен, то другие методы должны быть ориентированы на многопотоковое исполнение или сделать свои собственные приготовления для преобразования в последовательную форму.

SQLite никогда не будет вызывать xInit() несколько раз без прошедшего вызова xShutdown().

Обработка Mutex

typedef struct sqlite3_mutex sqlite3_mutex;

Модуль mutex в SQLite определяет sqlite3_mutex, чтобы быть абстрактным типом для объекта mutex. Ядро SQLite никогда не смотрит на внутреннее представление sqlite3_mutex. Это имеет дело только с указателями на объект sqlite3_mutex.

Mutex создаются, используя sqlite3_mutex_alloc().

Методы объекта Mutex

typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
struct sqlite3_mutex_methods {
  int (*xMutexInit)(void);
  int (*xMutexEnd)(void);
  sqlite3_mutex *(*xMutexAlloc)(int);
  void (*xMutexFree)(sqlite3_mutex *);
  void (*xMutexEnter)(sqlite3_mutex *);
  int (*xMutexTry)(sqlite3_mutex *);
  void (*xMutexLeave)(sqlite3_mutex *);
  int (*xMutexHeld)(sqlite3_mutex *);
  int (*xMutexNotheld)(sqlite3_mutex *);
};

Экземпляр этой структуры определяет код низкого уровня, используемый, чтобы ассигновать и использовать mutex.

Обычно mutex, обеспеченный SQLite, достаточен, однако у приложения есть выбор замены пользовательской реализацией для специализированного развертывания или систем, для которых SQLite не обеспечивает подходящее внедрение. В этом случае приложение создает и заполняет экземпляр этой структуры, чтобы передать sqlite3_config() наряду с выбором SQLITE_CONFIG_MUTEX. Кроме того, экземпляр этой структуры может использоваться в качестве выходной переменной, запрашивая систему для текущей реализации mutex, используя опцию SQLITE_CONFIG_GETMUTEX.

Метод xMutexInit, определенный этой структурой, вызван как часть системной инициализации функции sqlite3_initialize(). xMutexInit вызывает SQLite точно однажды для каждого эффективного вызова sqlite3_initialize().

Метод xMutexEnd, определенный этой структурой, вызван как часть завершения работы системного sqlite3_shutdown(). Внедрение этого метода, как ожидают, высвободит все выдающиеся средства, полученные mutex внедрением методов, особенно полученные xMutexInit. Интерфейс xMutexEnd() вызван точно однажды для каждого sqlite3_shutdown().

Остальные семь методов, определенные этой структурой (xMutexAlloc, xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld и xMutexNotheld) осуществляет следующие интерфейсы (соответственно):

• sqlite3_mutex_alloc()
• sqlite3_mutex_free()
• sqlite3_mutex_enter()
• sqlite3_mutex_try()
• sqlite3_mutex_leave()
• sqlite3_mutex_held()
• sqlite3_mutex_notheld()

Единственная разница: то, что функции public sqlite3_XXX, перечисленные выше, тихо игнорируют любые вызовы, которые передают NULL вместо действительного дескриптора mutex. Внедрения методов, определенных этой структурой, не требуются, чтобы обращаться с этим случаем. Результаты прохождения NULL вместо действительного дескриптора mutex не определены (то есть приемлемо обеспечить внедрение, которое выдаст segfaults, если это передает NULL).

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

xMutexInit() не должен использовать выделение памяти SQLite (sqlite3_malloc()). Точно так же xMutexAlloc() не должен использовать выделение памяти SQLite для статического mutex. Однако, xMutexAlloc() может использовать выделение памяти SQLite для быстрого или рекурсивного mutex.

SQLite вызовет xMutexEnd() когда вызван sqlite3_shutdown(), но только если предшествующий вызов xMutexInit вернул SQLITE_OK. Если xMutexInit потерпит неудачу в каком-либо случае, он, как ожидают, зачистит все ресурсы после себя до возвращения.

Объект заказного кэша страниц

typedef struct sqlite3_pcache sqlite3_pcache;

Тип sqlite3_pcache непрозрачен. Это осуществляется pluggable модулем. Ядро SQLite не знает о своем размере или внутренней структуре и никогда не имеет дело с объектом sqlite3_pcache кроме хранения и передачи указателей на него.

Объект кэша страниц

typedef struct sqlite3_pcache_page sqlite3_pcache_page;
struct sqlite3_pcache_page {
  void *pBuf;        /* The content of the page */
  void *pExtra;      /* Extra information associated with the page */
};

Объект sqlite3_pcache_page представляет единственную страницу в кэше страницы. Кэш ассигнует экземпляры этого объекта. Различные методы кэша используют указатели на экземпляры этого объекта как параметры или как их возвращаемое значение.

Название каталога, хранящего временные файлы

SQLITE_EXTERN char *sqlite3_temp_directory;

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

Не рекомендуется использовать эту глобальную переменную. Это требуется, чтобы устанавливать временную папку на Windows Runtime (WinRT). Но для всех других платформ настоятельно рекомендовано ее не трогать. Эта глобальная переменная пережиток, который существует для обратной совместимости унаследованных приложений.

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

Прагма temp_store_directory может изменить эту переменную и заставить ее указывать на память, полученную из sqlite3_malloc . Кроме того, temp_store_directory pragma всегда предполагает, что любая последовательность, на которую указывает эта переменная, проводится в памяти, полученной из sqlite3_malloc, а прагма может попытаться освободить ту память, используя sqlite3_free. Следовательно, если эта переменная изменяется непосредственно, это должно быть сделано NULL или указать на память, полученную из sqlite3_malloc, иначе прагмы temp_store_directory нужно избежать. Кроме тех случаев, когда вызвана прагма temp_store_directory pragma SQLite не освобождает память, на которую указывает sqlite3_temp_directory.

Для пользователей Windows Runtime: временный каталог должен быть установлен до запроса sqlite3_open или sqlite3_open_v2. Иначе различные особенности, которые требуют использования временных файлов, могут потерпеть неудачу. Вот пример того, как сделать это в C++ с Windows Runtime:

LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
      TemporaryFolder->Path->Data();
char zPathBuf[MAX_PATH + 1];
memset(zPathBuf, 0, sizeof(zPathBuf));
WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
      NULL, NULL);
sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);

Объект интерфейса OS

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in future versions.  The iVersion
  ** value will increment whenever this happens.
  */
};

Экземпляр объекта sqlite3_vfs определяет интерфейс между ядром SQLite и основной операционной системой. "vfs" это сокращение от "virtual file system".

Интерфейс VFS иногда расширяется, добавляя новые методы. Каждый раз, когда такое расширение происходит, поле iVersion растет. Значение iVersion начинается с 1 в SQLite version 3.5.0 on 2007-09-04, растет до 2 в SQLite version 3.7.0 on 2010-07-21 и до 3 в SQLite version 3.7.6 on 2011-04-12. Дополнительные области могут быть добавлены к объекту sqlite3_vfs и значение iVersion может увеличиться снова в будущих версиях SQLite. Обратите внимание на то, что из-за надзора, структура объекта sqlite3_vfs изменилась между версиями SQLite version 3.5.9 и version 3.6.0 on 2008-07-16, но поле iVersion не поменялось.

Поле szOsFile это размер структуры sqlite3_file в VFS. mxPathname максимальная длина пути в этом VFS.

Зарегистрированные объекты sqlite3_vfs сохранены в связанном списке, сформированном указателем pNext. Интерфейсы sqlite3_vfs_register() и sqlite3_vfs_unregister() управляют этим списком ориентированным на многопотоковое исполнение способом. Интерфейс sqlite3_vfs_find() ищет в списке. Ни код приложения, ни внедрение VFS не должны использовать указатель pNext.

Поле pNext это единственная область в sqlite3_vfs, которую будет когда-либо изменять SQLite. SQLite получит доступ или изменит эту область, только держа конкретный статический mutex. Приложение ничего никогда не должно изменять в объекте sqlite3_vfs, как только объект был зарегистрирован.

Поле zName хранит название модуля VFS. Имя должно быть уникальным через все модули VFS.

гарантирует, что параметр zFilename в xOpen это NULL или последовательность, полученная из xFullPathname() с дополнительным добавленным суффиксом. Если суффикс будет добавлен к параметру zFilename, он будет состоять из символа "-", сопровождаемого не больше, чем 11 алфавитно-цифровыми символами и/или "-". SQLite гарантирует, что последовательность будет действительна и неизменна до xClose(). Из-за предыдущего предложения sqlite3_file может безопасно сохранить указатель на имя файла, если это должно помнить имя файла по некоторым причинам. Если параметр zFilename в xOpen = NULL, xOpen должен изобрести его собственное временное имя файла. Каждый раз, когда xFilename = NULL будет также иметь место, что параметр флагов будет включать SQLITE_OPEN_DELETEONCLOSE.

Аргумент флагов xOpen() включает весь набор бит в аргумент флагов sqlite3_open_v2().Если применено sqlite3_open() или sqlite3_open16(), то флаги включают по крайней мере SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. Если xOpen() открывает файл как read-only, он устанавливает *pOutFlags, чтобы тот включал SQLITE_OPEN_READONLY. Другие биты в *pOutFlags могут быть установлены.

SQLite также добавит один из следующих флагов к xOpen(), в зависимости от открываемого объекта:

• SQLITE_OPEN_MAIN_DB
• SQLITE_OPEN_MAIN_JOURNAL
• SQLITE_OPEN_TEMP_DB
• SQLITE_OPEN_TEMP_JOURNAL
• SQLITE_OPEN_TRANSIENT_DB
• SQLITE_OPEN_SUBJOURNAL
• SQLITE_OPEN_SUPER_JOURNAL
• SQLITE_OPEN_WAL

Внедрение файлового ввода-вывода может использовать флаги типа объекта, чтобы изменить способ, которым оно имеет дело с файлами. Например, приложение, которое не заботится о восстановлении катастрофы или обратной перемотке, могло бы игнорировать файл журнала. Запись этого журнала была бы невозможна, а любая попытка прочитать журнал возвратит SQLITE_IOERR. Или внедрение могло бы признать, что файл базы данных будет выровнен по сектору, а чтение и запись идут в произвольном порядке, и настроило свою подсистему I/O соответственно.

SQLite мог бы также добавить один из следующих флагов к

• SQLITE_OPEN_DELETEONCLOSE
• SQLITE_OPEN_EXCLUSIVE

Флаг SQLITE_OPEN_DELETEONCLOSE означает, что файл должен быть удален, когда это закрывается. SQLITE_OPEN_DELETEONCLOSE будет установлен для баз данных TEMP и их журналов, переходных баз данных и поджурналов.

Флаг SQLITE_OPEN_EXCLUSIVE всегда используется вместе с флагом SQLITE_OPEN_CREATE, которые непосредственно аналогичны O_EXCL и O_CREAT в POSIX open() API. SQLITE_OPEN_EXCLUSIVE, когда соединен с SQLITE_OPEN_CREATE, используется, чтобы указать, что файл должен всегда создаваться, и что есть ошибка, если это уже существует. Это не используется, чтобы указать, что файл должен быть открыт для эксклюзивного доступа.

По крайней мере, szOsFile байт памяти ассигнуются SQLite, чтобы хранить структуру sqlite3_file как третий аргумент xOpen. Метод xOpen не должен ассигновать структуру, он должен просто ее заполнить. Обратите внимание на то, что метод xOpen должен установить sqlite3_file.pMethods в действительный объект sqlite3_io_methods или в NULL. xOpen должен сделать это, даже если открытие терпит неудачу. SQLite ожидает, что sqlite3_file.pMethods будет действителен после xOpen независимо от успешности или неуспешности xOpen.

Аргументом флагов xAccess() может быть SQLITE_ACCESS_EXISTS, чтобы проверить на существование файла или SQLITE_ACCESS_READWRITE, чтобы проверить, удобочитаемый ли файл и перезаписываемый, или SQLITE_ACCESS_READ, чтобы проверить, удобочитаемый ли файл, по крайней мере. Флаг SQLITE_ACCESS_READ на самом деле никогда не используется и не осуществляется во встроенном VFS SQLite. Имя файла это второй аргумент и может быть каталогом. Метод xAccess возвращает SQLITE_OK при успехе или некоторый код ошибки, отличный от нуля, если есть ошибка I/O или если название файла, данного во втором аргументе, неправильно. Если SQLITE_OK возвращен, то отличное от нуля или ноль вписано в *pResOut, чтобы указать, доступен ли файл.

SQLite будет всегда ассигновать, по крайней мере, mxPathname+1 байт для буфера вывода xFullPathname. Точный размер буфера вывода также передается в качестве параметра обоим методам. Если буфер вывода недостаточно большой, вернется SQLITE_CANTOPEN. Так как это обработано как фатальная ошибка SQLite, внедрения vfs должны пытаться предотвращать это, устанавливая mxPathname к достаточно большому значению.

Интерфейсы xRandomness(), xSleep(), xCurrentTime() и xCurrentTimeInt64() не строго часть файловой системы, но они включены в структуру VFS для полноты. xRandomness() пытается возвратить nBytes байт хаотичности хорошего качества в zOut. Возвращаемое значение это фактическое число байтов полученной хаотичности. xSleep() заставляет вызывающий поток спать по крайней мере данное число микросекунд. xCurrentTime() возвращает Julian Day Number для текущей даты и время как значение с плавающей точкой. xCurrentTimeInt64() вернет как целое число Julian Day Number, умноженное на 86400000 (количество миллисекунд в 24-часовой день). SQLite будет использовать метод xCurrentTimeInt64(), чтобы получить текущую дату и время, если тот метод будет доступен (если iVersion равняется 2 или больше и указатель функции не NULL) и отступит к xCurrentTime(), если xCurrentTimeInt64() недоступен.

Интерфейсы xSetSystemCall(), xGetSystemCall() и xNestSystemCall() не используются ядром SQLite. Эти дополнительные интерфейсы обеспечиваются некоторыми VFS, чтобы облегчить тестирование кода VFS. Наиважнейшими системными вызовами с функциями под ее контролем тестовая программа может моделировать ошибки и состояние ошибки, которое иначе было бы трудно или невозможным вызвать. Набор системных вызовов, которые могут быть отвергнуты, варьируется от одного VFS до другого, и от одной версии того же самого VFS к следующей. Запросы, которые используют эти интерфейсы, должны быть готовы к любым из этих интерфейсов быть NULL или к их поведению, чтобы измениться от одного выпуска до следующего. Запросы не должны пытаться получить доступ к любому из этих методов, если iVersion VFS меньше 3.

Виртуальный объект экземпляра таблицы

struct sqlite3_vtab {
  const sqlite3_module *pModule;  /* The module for this virtual table */
  int nRef;                       /* Number of open cursors */
  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  /* Virtual table implementations will typically add additional fields */
};

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

Виртуальные методы могут установить сообщение об ошибке, назначив последовательность, полученную из sqlite3_mprintf() в zErrMsg. Метод должен заботиться, что любая предшествующая последовательность освобождена вызовом sqlite3_free() до назначения новой последовательности zErrMsg. После того, как сообщение об ошибке дойдет до клиентского приложения, последовательность будет автоматически освобождена sqlite3_free(), а поле zErrMsg обнуляется.

Получите контекст агрегатной функции

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

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

В первый раз sqlite3_aggregate_context(C,N) вызывают для конкретной агрегатной функции, SQLite ассигнует N байт памяти, и возвращает указатель на новую память. На вторых и последующих вызовах sqlite3_aggregate_context() для того же самого случая агрегатной функции, возвращен тот же самый буфер. Sqlite3_aggregate_context() обычно вызывают однажды для каждого вызова xStep и затем один раз, когда вызван xFinal. Когда никакие строки не соответствуют агрегатному запросу, отзыв xStep() внедрения агрегатной функции никогда не вызывают, и xFinal() вызывают точно однажды. В тех случаях sqlite3_aggregate_context() мог бы быть вызван впервые из xFinal().

sqlite3_aggregate_context(C,N) вернет NULL при первом вызове, если N меньше или равен нолю, или если ошибка распределения памяти происходит.

Сумма места, выделенного sqlite3_aggregate_context(C,N), определяется параметром N при первом успешном вызове. Изменение N в любом последующем обращении к sqlite3_aggregate_context() в том же самом случае агрегатной функции не изменит размеры выделения памяти. В отзыве xFinal нормально установить N=0 в вызове sqlite3_aggregate_context(C,N), чтобы никакие бессмысленные выделения памяти не происходили.

SQLite автоматически освобождает память, ассигнованную sqlite3_aggregate_context(), когда агрегатный запрос заканчивается.

Первый параметр должен быть копией контекста функции SQL, который является первым параметром отзыва xStep или xFinal, который осуществляет агрегатную функцию.

Это нужно вызвать от того же самого потока, в котором работает совокупная функция SQL.

Автоматическая загрузка статически связанных расширений

int sqlite3_auto_extension(void(*xEntryPoint)(void));

Этот интерфейс заставляет вызвать функцию xEntryPoint() для каждого нового соединения с базой данных, которое создается. Идея здесь состоит в том, что xEntryPoint() является точкой входа для статически связанного расширения SQLite, которое должно быть автоматически загружено во все новые соединения с базой данных.

Даже при том, что прототип функции показывает, что xEntryPoint() не берет аргументов и вернет void, SQLite вызывает xEntryPoint() с тремя аргументами и ожидает результат целого числа как подпись точки входа следующим образом:

int xEntryPoint(sqlite3 *db, const char **pzErrMsg,
                const struct sqlite3_api_routines *pThunk);

Если xEntryPoint сталкивается с ошибкой, он должен заставить *pzErrMsg указать на соответствующее сообщение об ошибке (полученное из sqlite3_mprintf()) и возвратить соответствующий код ошибки. SQLite гарантирует, что *pzErrMsg NULL прежде, чем вызвать xEntryPoint(). SQLite вызовет sqlite3_free() для *pzErrMsg после возврата xEntryPoint(). Если какой-либо xEntryPoint() возвратит ошибку, sqlite3_open(), sqlite3_open16() или sqlite3_open_v2(), который вызвал xEntryPoint(), потерпит неудачу.

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

Автовакуумный отзыв уплотнения

int sqlite3_autovacuum_pages(sqlite3 *db, unsigned int(*)(void*,const char*,
                             unsigned int,unsigned int,unsigned int),
                             void*, void(*)(void*));

Интерфейс sqlite3_autovacuum_pages(D,C,P,X) регистрирует функцию обратного вызова C, которая вызвана до каждого автовакуума файла базы данных. Отзыву передается копия универсального указателя данных (P), имя схемы базы данных, которая вакуумируется, размер файла базы данных в страницах, число свободных страниц и число байтов на страницу. Отзыв должен возвратить число свободных страниц, которые должны быть удалены автовакуумом. Если отзыв возвращает ноль, то никакого автовакуума не происходит. Если возвращенное значение больше или равно числу свободных страниц, то полный автовакуум происходит.

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

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

Параметр X sqlite3_autovacuum_pages(D,C,P,X) является дополнительным деструктором для параметра P. Если X не NULL, то X(P) вызван каждый раз, когда соединение с базой данных закрывается или когда отзыв переписан другим вызовом sqlite3_autovacuum_pages().

Есть только один автовакуумный отзыв страниц на связь для каждой базы данных. Каждое обращение к sqlite3_autovacuum_pages() отвергает все предыдущие вызовы для этого соединения с базой данных. Если аргументом отзыва (C) для sqlite3_autovacuum_pages(D,C,P,X) = NULL, то автовакуумный отзыв отменяется. Возвращаемое значение от sqlite3_autovacuum_pages() обычно SQLITE_OK, но могло бы быть некоторым другим кодом ошибки, если что-то идет не так, как надо. Текущее внедрение возвратит только SQLITE_OK или SQLITE_MISUSE, но другие коды возврата могли бы быть добавлены в будущих выпусках.

Если никакой автовакуумный отзыв страниц не определяется (обычный случай) или NULL обеспечивается для отзыва, то поведение по умолчанию должно вакуумировать все свободные страницы. Так, другими словами, поведение по умолчанию совпадает с ситуацией, когда функция обратного вызова была чем-то вроде этого:

unsigned int demonstration_autovac_pages_callback(void *pClientData,
                                                  const char *zSchema,
                                                  unsigned int nDbPage,
                                                  unsigned int nFreePage,
                                                  unsigned int nBytePerPage)
{
  return nFreePage;
}

Количество параметров SQL

int sqlite3_bind_parameter_count(sqlite3_stmt*);

Это может использоваться, чтобы найти количество параметров SQL в подготовленном запросе. Параметры SQL это символы формы "?", "?NNN", ":AAA", "$AAA" или "@AAA", которые служат заполнителями для значений, которые связаны с параметрами в более позднее время.

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

Индекс параметра с именем

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

Возвратит индекс параметра SQL, данного как его имя. Возвращенное значение индекса подходит для использования в качестве второго параметра в sqlite3_bind(). Ноль возвращен, если никакой параметр соответствия не найден. Название параметра должно быть дано в UTF-8, даже если бы оригинальный запрос был подготовлен из текста UTF-16, используя sqlite3_prepare16_v2() или sqlite3_prepare16_v3().

Название параметра хоста

const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

Интерфейс sqlite3_bind_parameter_name(P,N) вернет имя N-го параметра SQL в подготовленном запросе P. Параметры SQL форм "?NNN", ":AAA", "@AAA" или "$AAA" имеют имя, которое является последовательностью "?NNN", ":AAA", "@AAA" или "$AAA", соответственно. Другими словами, начальный символ ":", "$", "@" или "?" включен как часть имени. Параметры формы "?" без следующего целого числа не имеют никакого имени и упоминаются как "nameless" или "anonymous parameters".

У первого параметра есть индекс 1, не 0.

Если N вне диапазона или если N-ный параметр неназванный, то NULL возвращен. Возвращаемая строка всегда находится в UTF-8, даже если названный параметр был первоначально определен как UTF-16 в sqlite3_prepare16(), sqlite3_prepare16_v2() или sqlite3_prepare16_v3().

Возвратит размер открытого BLOB

int sqlite3_blob_bytes(sqlite3_blob *);

Возвращает размер в байтах BLOB, доступного через успешно открытый обработчик BLOB в ее единственном аргументе. I/O может только читать или переписывать существующий blob, изменить размер нельзя.

Это работает только с обработчиком BLOB, который был создан предшествующим успешным вызовом sqlite3_blob_open() и не был закрыт sqlite3_blob_close(). Передача любого другого указателя приводит к неопределенному и вероятно нежелательному поведению.

Закрыть обработчик BLOB

int sqlite3_blob_close(sqlite3_blob *);

Эта функция закрывает открытый обработчик BLOB. Даже если этот вызов возвращает код ошибки, обработчик все равно закрывается.

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

Вызов этой функции с аргументом, который не является NULL или открытым обработчиком blob приведет к неопределенному поведению. Запрос с нулевым указателем (тем, который был бы возвращен неудавшимся sqlite3_blob_open()) является безопасным. Иначе, если этой функции передается действительный открытый обработчик blob, значения, возвращенные функциями sqlite3_errcode() и sqlite3_errmsg() установлены перед возвращением.

Открыть BLOB для возрастающего I/O

int sqlite3_blob_open(sqlite3*, const char *zDb, const char *zTable,
                      const char *zColumn, sqlite3_int64 iRow, int flags,
                      sqlite3_blob **ppBlob);

Это открывает обработчик для BLOB в строке iRow, колонке zColumn, таблицы zTable БД zDb, другими словами, тот же самый BLOB, который был бы выбран:

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

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

Если параметр флагов отличен от нуля, то BLOB открыт для чтения и записи. Если параметр флагов ноль, BLOB открыт только для чтения.

При успехе возвращен SQLITE_OK и новый обработчик BLOB записан в *ppBlob. Иначе возвращен код ошибки и, если код ошибки не SQLITE_MISUSE, *ppBlob установлен в NULL. Это означает, что, если API правильно используется, всегда безопасно вызвать sqlite3_blob_close() на *ppBlob после этой функции.

Эта функция терпит неудачу с SQLITE_ERROR, если что-либо следующее верно:

• БД zDb не существует,
• Таблица zTable не существует в базе данных zDb,
• Таблица zTable это таблица WITHOUT ROWID,
• Столбец zColumn не существует,
• Строки iRow в таблице нет,
• Указанная колонка строки iRow содержит значение, которое не является TEXT или BLOB,
• Столбец zColumn часть индекса, ограничения PRIMARY KEY или UNIQUE, а blob открывается для доступа для чтения-записи,
• Ограничения внешнего ключа позволены, колонка zColumn часть определения дочернего ключа и blob открывается для доступа для чтения-записи.

Если это не возвращает SQLITE_MISUSE, эта функция устанавливает код ошибки соединения с базой данных и сообщение, доступное через sqlite3_errcode() и sqlite3_errmsg().

BLOB, на который ссылается sqlite3_blob_open(), может быть прочитан, используя интерфейс sqlite3_blob_read() и изменен при помощи sqlite3_blob_write(). Обработчик BLOB может быть перемещен в другую строку той же самой таблицы, используя интерфейс sqlite3_blob_reopen(). Однако колонка, таблица или база данных не могут быть изменены после того, как открыт обработчик BLOB.

Если строка, на которую указывает обработчик BLOB, изменяется UPDATE, DELETE, или ON CONFLICT, обработчик помечается как "expired". Это верно, если какая-либо колонка строки изменяется, даже колонка кроме той, где находится обработчик. Вызов sqlite3_blob_read() и sqlite3_blob_write() для expired BLOB терпят неудачу с кодом возврата SQLITE_ABORT. Изменения, написанные в BLOB до истечения BLOB, не отменены истечением BLOB. Такие изменения в конечном счете передадут, если транзакция продолжится до завершения.

Используйте интерфейс sqlite3_blob_bytes() , чтобы определить размер открытого blob. Размер blob не может быть изменен этим интерфейсом. Используйте SQL-команду UPDATE, чтобы изменить размер blob.

Интерфейсы sqlite3_bind_zeroblob() и sqlite3_result_zeroblob() и встроенная SQL-функция zeroblob могут использоваться, чтобы создать заполненный нулями blob, чтобы прочитать или написать с использованием интерфейса incremental-blob.

Чтобы избежать утечки ресурсов, каждый открытый обработчик BLOB должен в конечном счете быть закрыт вызовом sqlite3_blob_close().

См. также: sqlite3_blob_close(), sqlite3_blob_reopen(), sqlite3_blob_read(), sqlite3_blob_bytes(), sqlite3_blob_write().

Прочитайте данные из BLOB с приращением

int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

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

Если iOffset меньше N байт от конца BLOB, возвращена ошибка SQLITE_ERROR и никакие данные не прочитаны. Если N или iOffset меньше, чем ноль, возвращена ошибка SQLITE_ERROR и никакие данные не прочитаны. Размер blob (и следовательно максимальное значение N+iOffset) может быть определен, используя интерфейс sqlite3_blob_bytes().

Попытка читать от обработчика BLOB с истекшим сроком терпит неудачу с кодом ошибки SQLITE_ABORT.

При успехе sqlite3_blob_read() вернет SQLITE_OK. Иначе код ошибки или расширенный код ошибки.

Это работает только с обработчиками BLOB, который был создан предшествующим успешным вызовом sqlite3_blob_open() и не закрыт sqlite3_blob_close(). Передача любого другого указателя приводит к неопределенному и вероятно нежелательному поведению.

См. также: sqlite3_blob_write().

Переместите обработчик BLOB в новую строку

int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);

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

Новая строка должна соответствовать тем же самым критериям что касаются sqlite3_blob_open(): это должно существовать и должно быть значением blob или text, сохраненным в номинируемой колонке. Если новая строка не присутствует в таблице, или если это не содержит значение blob или text, или если другая ошибка происходит, код ошибки SQLite возвращен, и обработчик считают прерванным. Все последующие вызовы sqlite3_blob_read(), sqlite3_blob_write() или sqlite3_blob_reopen() к этому обработчику немедленно возвращают SQLITE_ABORT. Запрос sqlite3_blob_bytes() всегда возвращает ноль.

Эта функция устанавливает код ошибки обработки базы данных и сообщение.

Запись данных в BLOB

int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

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

При успехе sqlite3_blob_write() вернет SQLITE_OK. Иначе она вернет код ошибки или расширенный код ошибки. Если SQLITE_MISUSE не возвращен, эта функция устанавливает код ошибки соединения с базой данных и сообщение, доступное через sqlite3_errcode() и sqlite3_errmsg().

Если обработчик BLOB, переданный как первый аргумент, не был открыт для записи (параметр флагов sqlite3_blob_open() был нолем), эта функция возвращает SQLITE_READONLY.

Эта функция может только изменить содержание BLOB, невозможно увеличить размер BLOB, используя этот API. Если iOffset меньше N байт от конца BLOB, SQLITE_ERROR возвращен, и никакие данные не написаны. Размер BLOB (и следовательно максимальное значение N+iOffset) может быть определен, используя интерфейс sqlite3_blob_bytes(). Если N или iOffset меньше нуля, возвращается SQLITE_ERROR и никакие данные не написаны.

Попытка написать обработчик BLOB с истекшим сроком терпит неудачу с кодом ошибки SQLITE_ABORT. Записи BLOB, которые произошли перед истекшим сроком не отменены, хотя, конечно, те изменения, возможно, были переписаны запросом.

Это работает только с BLOB, созданными sqlite3_blob_open() и не закрытыми sqlite3_blob_close(). Передача любого другого указателя приводит к неопределенному и вероятно нежелательному поведению.

См. также: sqlite3_blob_read().

Установите занятый тайм-аут

int sqlite3_busy_timeout(sqlite3*, int ms);

Это ставит обработчик, который спит указанное количество времени, когда таблица блокирована. Он будет спать многократно до по крайней мере "ms" миллисекунд сна. После по крайней мере "ms" миллисекунд сна обработчик возвращает 0, что заставляет sqlite3_step() вернуть SQLITE_BUSY.

Запрос этого меньше или равным нолю, выключает всех обработчиков.

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

См. также: PRAGMA busy_timeout

Отмените автоматическую загрузку расширений

int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));

sqlite3_cancel_auto_extension(X) снимает регистрацию кода инициализации X, которая была зарегистрирована, используя предшествующий вызов sqlite3_auto_extension(X). sqlite3_cancel_auto_extension(X) вернет 1, если все нормально, или 0, если X не был в списке кодов инициализации.

Перезагрузите все привязки на подготовленном запросе

int sqlite3_clear_bindings(sqlite3_stmt*);

sqlite3_reset() не перезагружает bindings на подготовленном запросе. Используйте эту функцию, чтобы перезагрузить все параметры в NULL.

Количество колонок в наборе результатов

int sqlite3_column_count(sqlite3_stmt *pStmt);

Возвратит количество колонок в наборе результатов, возвращенном подготовленным запросом. Если это вернет 0, значит запрос не вернул данные (например, UPDATE). Однако то, что это возвращает положительное число не означает, что будут возвращены одна или несколько строк данных. У оператора SELECT всегда будет положительный sqlite3_column_count(), но в зависимости от ограничений оператора Where и содержания таблицы, он мог бы и не возвратить строки.

См. также: sqlite3_data_count()

Настройка библиотеки SQLite

int sqlite3_config(int, ...);

Интерфейс sqlite3_config() используется, чтобы сделать глобальные изменения конфигурации к SQLite, чтобы настроить SQLite на определенные потребности применения. Конфигурация по умолчанию рекомендуется для большинства запросов и таким образом, этот установленный порядок обычно не нужен. Это обеспечивается, чтобы поддержать редкие приложения с необычными потребностями.

Интерфейс sqlite3_config() не ориентирован на многопотоковое исполнение. Применение должно гарантировать, что никакие другие интерфейсы SQLite не вызваны другими потоками в то время, как работает sqlite3_config().

Первым аргументом sqlite3_config() является integer опция анстройки, которая определяет, какое свойство SQLite настраивать. Последующие аргументы варьируются в зависимости от этого.

Для большинства параметров конфигурации интерфейс sqlite3_config() может быть вызван только до инициализации библиотеки, используя sqlite3_initialize() или после закрытия через sqlite3_shutdown(). Исключительные параметры конфигурации, которые могут быть вызваны в любое время, называют "параметры конфигурации любого времени". Если sqlite3_config() вызван после sqlite3_initialize(), но до sqlite3_shutdown() с первым аргументом, который не является параметром конфигурации в любое время, то sqlite3_config() вернет SQLITE_MISUSE. Отметьте, однако, что sqlite3_config() можно вывать как часть внедрения определенного применением sqlite3_os_init().

Когда параметр конфигурации установлен, sqlite3_config() вернет SQLITE_OK. Если выбор неизвестен или SQLite неспособен установить его, этот код возвращает ненулевой код ошибки.

Соединение с базой данных для функций

sqlite3 *sqlite3_context_db_handle(sqlite3_context*);

Интерфейс sqlite3_context_db_handle() возвращает копию указателя на соединение с базой данных (1-й параметр) sqlite3_create_function() и sqlite3_create_function16(), который первоначально зарегистрировался, когда приложение определило функцию.

Количество колонок в наборе результатов

int sqlite3_data_count(sqlite3_stmt *pStmt);

Интерфейс sqlite3_data_count(P) возвращает количество колонок в текущей строке набора результатов P. Если у подготовленного запроса P нет результатов, готовых к возврату (через интерфейсы sqlite3_column()), sqlite3_data_count(P) вернет 0. sqlite3_data_count(P) также вернет 0, если P = NULL. sqlite3_data_count(P) вернет 0, если прошлый вызов sqlite3_step(P) вернул SQLITE_DONE. sqlite3_data_count(P) возвратит отличное от нуля значение, если предыдущий вызов sqlite3_step(P) вернул SQLITE_ROW, кроме случая PRAGMA incremental_vacuum , тогда это всегда возвращает ноль, начиная с шага, на котором многоступенчатая прагма возвращает 0 колонок данных.

См. также: sqlite3_column_count()

Файл базы данных, соответствующий журналу

sqlite3_file *sqlite3_database_file_object(const char*);

Если X название файла журнала обратной перемотки или режима WAL, который передается в метод xOpen sqlite3_vfs, то sqlite3_database_file_object(X) вернет указатель на объект sqlite3_file, который представляет главный файл базы данных.

Это предназначается для использования только во внедрениях VFS. Это не интерфейс общего назначения. Аргументом sqlite3_file_object(X) должен быть указателем на имя файла, который был передан в sqlite3_vfs.xOpen, где параметр флагов xOpen содержит один из битов SQLITE_OPEN_MAIN_JOURNAL или SQLITE_OPEN_WAL. Любое другое использование этого приводит к неопределенному и вероятно нежелательному поведению.

Сброс кэшей на диск

int sqlite3_db_cacheflush(sqlite3*);

Если транзакция записи открыта на соединении с базой данных D, когда вызван интерфейс sqlite3_db_cacheflush(D), любые грязные страницы в кэше страниц, которые не используются в настоящее время, сброшены на диск. Грязная страница может использоваться, если курсор базы данных, созданный активным SQL-оператором, читает с нее, или если это страница 1 файла базы данных (страница 1 всегда "в использовании"). Интерфейс sqlite3_db_cacheflush(D) сбросит кжши для всех схем: "main", "temp" и любых присоединенных БД.

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

Если какая-либо другая ошибка происходит, сбрасывая грязные страницы к диску (например, ошибка IO или нехватка памяти), то обработка оставлена, и SQLite немедленно вернет код ошибки.

Иначе, если никакая ошибка не происходит, sqlite3_db_cacheflush() вернет SQLITE_OK.

Эта функция не устанавливает код ошибки обработчика базы данных или сообщение, возвращенное sqlite3_errcode() и sqlite3_errmsg().

Настройка соединения с базой данных

int sqlite3_db_config(sqlite3*, int op, ...);

Интерфейс sqlite3_db_config() используется, чтобы сделать изменения конфигурации соединения с базой данных. Интерфейс подобен sqlite3_config() за исключением того, что изменения относятся к одному соединению с базой данных (определенному в первом аргументе).

Вторым аргументом sqlite3_db_config(D,V,...) является параметр настройки код integer, который указывает на то, какой аспект соединения с базой данных настроить. Последующие аргументы варьируются в зависимости от этого.

Обращения к sqlite3_db_config() возвращают SQLITE_OK, если и только если вызов считают успешным.

Возвратите имя файла для соединения с базой данных

sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);

Интерфейс sqlite3_db_filename(D,N) возвращает указатель на имя файла, связанное с базой данных N соединения D. Если не будет никакой базы данных N по соединению с базой данных D или если база данных N будет временной или базой данных в памяти, то эта функция возвратит NULL или пустую строку.

Значение последовательности, возвращенной этим кодом, принадлежит и управляется соединением с базой данных. Значение будет действительно, пока база данных N не будет DETACH или пока соединение с базой данных не закрывается.

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

Если указателем имени файла, возвращенным этой функцией, не является NULL, то это может использоваться в качестве входного параметра имени файла к:

• sqlite3_uri_parameter()
• sqlite3_uri_boolean()
• sqlite3_uri_int64()
• sqlite3_filename_database()
• sqlite3_filename_journal()
• sqlite3_filename_wal()

Найдите обработчик базы данных подготовленного запроса

sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

Интерфейс sqlite3_db_handle вернет обработчик соединения с базой данных, которой принадлежит подготовленному запросу. Соединение с базой данных, возвращенное sqlite3_db_handle, является тем же самым, которое было первым аргументом sqlite3_prepare_v2() (или его вариантов), который использовался, чтобы создать запрос изначально.

Получить mutex для соединения с базой данных

sqlite3_mutex *sqlite3_db_mutex(sqlite3*);

Интерфейс возвращает указатель на объект sqlite3_mutex, который преобразовывает в последовательную форму доступа к соединению с базой данных , данному в аргументе, когда поточный режим преобразовывается в последовательную форму. Если поточный режим это Single-thread или Multi-thread, вернется указатель NULL.

Возвратите название схемы соединения с базой данных

const char *sqlite3_db_name(sqlite3 *db, int N);

Интерфейс sqlite3_db_name(D,N) возвращает указатель на название схемы базы данных N по соединению с базой данных D или NULL, если N вне диапазона. Значение N = 0 означает главный файл базы данных. N = 1 является схемой "temp". Большие значения N соответствуют различным базам данных.

Местом, чтобы держать последовательность, которая возвращена sqlite3_db_name(), управляет сам SQLite. Последовательность могла бы быть освобождена любой операцией, которая изменяет схему, включая ATTACH, DETACH, вызовом sqlite3_serialize() или sqlite3_deserialize(), даже операции, которые происходят в другом потоке. Приложения, которые должны помнить долгосрочную последовательность, должны сделать свою собственную копию. Приложения, которые получают доступ к тому же самому соединению с базой данных одновременно на разных потоках, должны mutex-защитить вызовы этого API и сделать их собственную частную копию результата до освобождения mutex.

Определите, только ли для чтения база данных

int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);

Интерфейс sqlite3_db_readonly(D,N) вернет 1, если база данных N связи D только для чтения, 0 если это чтение-запись или -1, если N не название базы данных по связи D.

Освободить память, используемую соединением с базой данных

int sqlite3_db_release_memory(sqlite3*);

Интерфейс sqlite3_db_release_memory(D) пытается освободить как можно больше памяти кучи от соединения с базой данных D. В отличие от интерфейса sqlite3_release_memory(), этот этот интерфейс работает, даже когда опция времени компиляции SQLITE_ENABLE_MEMORY_MANAGEMENT пропущена.

См. также: sqlite3_release_memory()

Статус соединения с базой данных

int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr,int resetFlg);

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

Текущее значение требуемого параметра вписывается в *pCur, самое высокое мгновенное значение вписывается в *pHiwtr. Если resetFlg = true, то самое высокое мгновенное значение перезагружается к текущему.

sqlite3_db_status() вернет SQLITE_OK при успехе и не нулевой код ошибки при неудаче.

См. также: sqlite3_status() и sqlite3_stmt_status().

Декларирует схему виртуальной таблицы

int sqlite3_declare_vtab(sqlite3*, const char *zSQL);

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

Десериализуйте базу данных

int sqlite3_deserialize(
  sqlite3 *db,            /* The database connection */
  const char *zSchema,    /* Which DB to reopen with the deserialization */
  unsigned char *pData,   /* The serialized database content */
  sqlite3_int64 szDb,     /* Number bytes in the deserialization */
  sqlite3_int64 szBuf,    /* Total size of buffer pData[] */
  unsigned mFlags         /* Zero or more SQLITE_DESERIALIZE_* flags */
);

Интерфейс sqlite3_deserialize(D,S,P,N,M,F) заставляет соединение с базой данных D отсоединиться от базы данных S и затем вновь открыть S как базу данных в памяти на основе преобразования в последовательную форму содержавшегося в P. Преобразованная в последовательную форму база данных P будет N байт в размере. M это размер буфера P, который мог бы быть больше, чем N. Если M больше N и бит SQLITE_DESERIALIZE_READONLY не установлен в F, SQLite разрешают добавить содержание к базе данных в памяти, пока полный размер не превышает M байт.

Если бит SQLITE_DESERIALIZE_FREEONCLOSE утсановлен в F, SQLite вызовет sqlite3_free() на буфере преобразования в последовательную форму, когда соединение с базой данных закроется. Если бит SQLITE_DESERIALIZE_RESIZEABLE установлен, то SQLite попытается увеличить размер буфера, используя sqlite3_realloc64(), если записи в базу данных заставляют его первысить M байт.

Приложения не должны изменять буфер P или лишать его законной силы, прежде чем соединение с базой данных D будет закрыто.

Интерфейс sqlite3_deserialize() потерпит неудачу с SQLITE_BUSY, если база данных в настоящее время будет в транзакции чтения или будет вовлечена в операцию резервного копирования.

Невозможна десериализация БД TEMP. Если аргумент S в sqlite3_deserialize(D,S,P,N,M,F) = "temp", то функция возвращает SQLITE_ERROR.

Десериализованная база данных не должна быть в режиме WAL. Если база данных будет в режиме WAL, то любая попытка использовать файл базы данных приведет к ошибке SQLITE_CANTOPEN. Приложение может установить номера версий формата файла (байты 18 и 19) входной базы данных P в 0x01 до вызова sqlite3_deserialize(D,S,P,N,M,F), чтобы перевести файл базы данных в режим обратной перемотки и обойти эту проблему.

Если sqlite3_deserialize(D,S,P,N,M,F) терпит неудачу по какой-либо причине и если бит SQLITE_DESERIALIZE_FREEONCLOSE установлен в аргументе F, то sqlite3_free() вызван на аргумент P до возвращения.

Этот интерфейс опущен, если SQLite собран с опцией SQLITE_OMIT_DESERIALIZE.

Удалите ненужные виртуальные таблицы

int sqlite3_drop_modules(
  sqlite3 *db,                /* Remove modules from this connection */
  const char **azKeep         /* Except, do not remove the ones named here */
);

Интерфейс sqlite3_drop_modules(D,L) удаляет все виртуальные модули таблиц из соединения с базой данных D, кроме названных в списке L. Параметр L должен быть NULL или указателем на множество указателей на последовательности, где множество закончено единственным NULL. Если параметр L = NULL, то все виртуальные модули удалены.

См. также: sqlite3_create_module()

Включите или отключите загрузку дополнений

int sqlite3_enable_load_extension(sqlite3 *db, int onoff);

Чтобы не открыть дыры в системе безопасности в более старых запросах, которые не подготовлены, чтобы иметь дело с загрузкой дополнений, и как средство отключения загрузки дополнений, оценивая введенный пользователями SQL, следующий API обеспечивается, чтобы управлять механизмом sqlite3_load_extension().

Загрузка дополнений выключена по умолчанию. Вызов sqlite3_enable_load_extension() с onoff==1 включает, а с onoff==0 выключает ее.

Этот интерфейс управляет C API sqlite3_load_extension() и функцией SQL load_extension() . Используйте sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,..), чтобы управлять только C API.

Предупреждение безопасности: рекомендуется, чтобы загрузка расширения была позволена, используя метод SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, а не этот интерфейс, таким образом, функция SQL load_extension() остается отключенной. Это будет препятствовать тому, чтобы SQL injections предоставили доступ нападавших к возможностям загрузки расширения.

Включить или выключить кэш общих страниц

int sqlite3_enable_shared_cache(int);

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

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

Кэш управляется для всего процесса. Это изменение с SQLite version 3.5.0 (2007-09-04). В предыдущих версиях SQLite разделение было позволено или отключено для каждого потока отдельно.

Режим совместного использования кэша, установленный этим интерфейсом, влияет на все последующие вызовы sqlite3_open(), sqlite3_open_v2() и sqlite3_open16(). Существующие соединения с базой данных продолжают использовать режим совместного использования, который был в действительности в то время, когда они были открыты.

Это вернет SQLITE_OK, если общий кэш был позволен или отключен успешно. Иначе вернется код ошибки.

Общий кэш отключен по умолчанию. Рекомендуется, чтобы это осталось именно так. Другими словами, не используйте эту возможность. Этот интерфейс продолжает обеспечиваться для исторической совместимости, но использование осуждается. Если общий кэш должен использоваться, рекомендуется, чтобы общий кэш был позволен только для отдельных соединений с базой данных, используя интерфейс sqlite3_open_v2() с флагом SQLITE_OPEN_SHAREDCACHE.

Примечание: Этот метод отключен в MacOS X 10.7 и в iOS version 5.0 и будет всегда возвращать SQLITE_MISUSE. На тех системах разделенному режиму кэширования нужно позволить связь для каждой базы данных через sqlite3_open_v2() с SQLITE_OPEN_SHAREDCACHE.

Этот интерфейс ориентирован на многопоточное исполнение на процессорах, где написание 32-битного целого числа атомное.

См. также: SQLite Shared-Cache Mode

Интерфейс выполнения запросов с одним шагом

int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

Интерфейс sqlite3_exec() это обертка удобства вокруг sqlite3_prepare_v2(), sqlite3_step() и sqlite3_finalize(), который позволяет управлять многочисленными запросами SQL, не имея необходимости использовать много кода C.

Интерфейс sqlite3_exec() управляет нолем или большим количеством разделенных точкой с запятой SQL-операторов, переданных в UTF-8 в его 2-й аргумент в контексте соединения с базой данных, переданного как его 1-й аргумент. Если функция обратного вызова 3-го аргумента sqlite3_exec() не NULL, то это вызвано для каждой строки результата из оцененных SQL-операторов. 4-й аргумент sqlite3_exec() передается через 1-й аргумент каждого отзыва. Если указатель отзыва на sqlite3_exec() = NULL, то никакой отзыв никогда не вызывается, и строки результата проигнорированы.

Если ошибка происходит, оценивая SQL-операторы, переданные в sqlite3_exec(), то выполнение текущего запроса остановлено и последующие запросы пропущены. Если 5-м параметром sqlite3_exec() не является NULL, любое сообщение об ошибке написано в память, полученную из sqlite3_malloc(), и переданное назад через 5-й параметр. Чтобы избежать утечек памяти, приложение должно вызвать sqlite3_free() на последовательностях сообщения об ошибке, возвращенных через 5-й параметр sqlite3_exec() после того, как последовательность сообщения об ошибке больше не будет необходима. Если 5-й параметр sqlite3_exec() не NULL и никакие ошибки не происходят, то sqlite3_exec() устанавливает указатель в своем 5-м параметре в NULL перед возвращением.

Если отзыв sqlite3_exec() вернет отличное от нуля, sqlite3_exec() возвращает SQLITE_ABORT, не вызывая отзыв снова и не управляя никакими последующими SQL-операторами.

2-м аргументом sqlite3_exec() является количество колонок в результате. 3-м аргументом sqlite3_exec() является множество указателей на последовательности, полученные как будто от sqlite3_column_text(), один для каждой колонки. Если элемент ряда результата NULL, тогда соответствующий указатель строки для отзыва sqlite3_exec() = NULL. 4-й аргумент отзыва sqlite3_exec() множество указателей на последовательности, где каждый вход представляет название соответствующего столбца результата, как получено из sqlite3_column_name().

Если 2-й параметр sqlite3_exec() = NULL, указателем на пустую строку или указателем, который содержит только пробелы и/или комментарии SQL, то никакие SQL-операторы не оценены, и база данных не изменяется.

Ограничения:

• Приложение должно гарантировать, что 1-й параметр sqlite3_exec() является действительным и открытым соединением с базой данных.
• Приложение не должно закрывать соединение с базой данных, определенное 1-м параметром sqlite3_exec(), в то время как sqlite3_exec() работает.
• Приложение не должно изменять текст SQL-оператора, переданный во 2-й параметр sqlite3_exec() во время работы sqlite3_exec().

Позвольте или отключите расширенные коды результата

int sqlite3_extended_result_codes(sqlite3*, int onoff);

sqlite3_extended_result_codes() включает/выключает расширенную кодовую опцию SQLite. Расширенные коды результата отключены по умолчанию для исторической совместимости.

Разрушьте подготовленный объект запроса

int sqlite3_finalize(sqlite3_stmt *pStmt);

Функция sqlite3_finalize() нужна, чтобы удалить подготовленный запрос. Если новая оценка запроса не столкнулась ни с какими ошибками или если запрос никогда не оценен, то sqlite3_finalize() вернет SQLITE_OK. Если новая оценка запроса S потерпела неудачу, то sqlite3_finalize(S) возвращает соответствующий код ошибки или расширенный код ошибки.

sqlite3_finalize(S) можно вызвать в любом пункте во время жизненного цикла подготовленного запроса S: прежде чем S когда-либо оценивается, после одного или более вызовов sqlite3_reset() или после любого вызова sqlite3_step() независимо от того, закончил ли запрос выполнение.

Вызов sqlite3_finalize() с NULL ничего не делает.

Приложение должно завершить каждый подготовленный запрос, чтобы избежать утечек ресурсов. Это печальная ошибка попытаться использовать подготовленный запрос после того, как это было завершено. Любое использование подготовленного запроса после того, как это было завершено, может привести к неопределенному и нежелательному поведению, такому как повреждение кучи и segfaults.

Последняя вставка Rowid

sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);

У каждого входа в большинстве таблиц SQLite (кроме таблиц WITHOUT ROWID) есть уникальный 64-битный ключ целого числа со знаком, названный "rowid". rowid всегда доступен как необъявленная колонка под названием ROWID, OID или _ROWID_, пока те имена также не используются явно заявленными колонками. Если у таблицы есть колонка типа INTEGER PRIMARY KEY, она другой псевдоним для rowid.

Интерфейс sqlite3_last_insert_rowid(D) обычно возвращает rowid нового успешного INSERT в rowid-таблицу или виртуальную таблицу на соединении с базой данных D. Вставки в таблицы WITHOUT ROWID не зарегистрированы. Если никакой успешный INSERT в rowid-таблицы никогда не происходил на соединении с базой данных D, то sqlite3_last_insert_rowid(D) возвращает ноль.

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

Некоторые виртуальные внедрения таблицы могут вставить строки в rowid-таблицы как часть совершения транзакции (например, сбросить данные, накопленные в памяти, на диск). В этом случае последующие вызовы этой функции возвращают rowid, связанный с этими внутренними операциями INSERT, который приводит к неинтуитивным результатам. Виртуальные внедрения таблицы, которые действительно пишут rowid-таблицы таким образом, могут избежать этой проблемы, восстановив первоначальное значение rowid, используя sqlite3_set_last_insert_rowid() перед возвращением контроля пользователю.

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

INSERT, который терпит неудачу из-за ограничительного нарушения, не является успешным INSERT и не изменяет значение, возвращенное этой функцией. Таким образом, INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK и INSERT OR ABORT не вносят изменения в возвращаемое значение этого установленного порядка, когда их вставка терпит неудачу. Когда INSERT OR REPLACE сталкивается с ограничительным нарушением, он не терпит неудачу. INSERT продолжается к завершению после удаления строк, которые вызвали ограничительную проблему, так что INSERT OR REPLACE будет всегда изменять возвращаемое значение этого интерфейса.

В целях этого установленного порядка INSERT считается успешным, даже если это впоследствии отменено.

Эта функция доступна для SQL-операторов через SQL-функцию last_insert_rowid().

Если отдельный поток выполняет новый INSERT на том же самом соединении с базой данных, в то время как sqlite3_last_insert_rowid() работает и таким образом изменяет последнюю вставку rowid, то значение, возвращенное sqlite3_last_insert_rowid(), непредсказуемо и не могло бы равняться старому или новой последней вставке rowid.

Пределы во время выполнения

int sqlite3_limit(sqlite3*, int id, int newVal);

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

Если новый предел это отрицательное число, предел неизменен. Для каждой категории предела SQLITE_LIMIT_NAME это твердая верхняя граница, установленная во время компиляции макросом препроцессора C под названием SQLITE_MAX_NAME. "_LIMIT_" в имени изменяется на "_MAX_". Попытки увеличить предел выше его твердой верхней границы тихо усечены к твердой верхней границе.

Независимо от того, был ли предел изменен, интерфейс sqlite3_limit() возвращает предшествующее значение предела. Следовательно, чтобы найти текущее значение предела, не изменяя его, просто вызовите это с третьим параметром -1.

Пределы во время выполнения предназначаются для использования в запросах, которые управляют и их собственной внутренней базой данных и также базами данных, которыми управляют внешние источники, которым не доверяют. Пример приложения мог бы быть веб-браузером, у которого есть его собственные базы данных для хранения истории и отдельных баз данных, которыми управляют приложения JavaScript, загруженные из Интернета. Внутренним базам данных можно дать большие пределы по умолчанию. Базам данных, управляемым внешними источниками, можно дать намного меньшие пределы, разработанные, чтобы предотвратить атаку "отказ в обслуживании". Разработчики могли бы также хотеть использовать интерфейс sqlite3_set_authorizer(), чтобы далее управлять SQL, которому не доверяют. Размер базы данных, созданной скриптом, которому не доверяют, может быть настроен, используя прагму max_page_count.

Новые категории предела во время выполнения могут быть добавлены в будущих выпусках.

Загрузка расширений

int sqlite3_load_extension(
  sqlite3 *db,          /* Load the extension into this database connection */
  const char *zFile,    /* Name of the shared library containing extension */
  const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  char **pzErrMsg       /* Put error message here if not 0 */
);

Этот интерфейс загружает дополнительную библиотеку SQLite от названного файла.

Интерфейс sqlite3_load_extension() пытается загрузить дополнительную библиотеку SQLite, содержавшуюся в файле zFile. Если файл не может быть загружен непосредственно, попытки предприняты, чтобы загрузить с различными определенными операционной системой добавленными расширениями. Так, например, если "samplelib" не может быть загружен, то такие имена, как "samplelib.so", "samplelib.dylib" или "samplelib.dll" можно было бы также попробовать.

Точка входа zProc. zProc может быть 0, в этом случае SQLite попытается придумать имя точки входа самостоятельно. Это сначала пробует "sqlite3_extension_init". Если это не работает, это строит имя "sqlite3_X_init", где X состоит из строчного эквивалента всех буквенных символов ASCII в имени файла от последнего "/" к первому следующему символу ".", опуская любой начальный "lib". Интерфейс sqlite3_load_extension() возвращает SQLITE_OK при успехе и SQLITE_ERROR, если что-то идет не так, как надо. Если ошибка произойдет, и pzErrMsg не 0, sqlite3_load_extension() должен попытаться заполнить *pzErrMsg текстом сообщения об ошибке, сохраненным в памяти, полученной из sqlite3_malloc(). Функция запроса должна освободить эту память через sqlite3_free().

Дополнительная загрузка должна быть позволена, используя sqlite3_enable_load_extension() или sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL) до запроса этого API, иначе ошибка будет возвращена.

ПРЕДУПРЕЖДЕНИЕ: рекомендуется, чтобы метод SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION использовался только этим интерфейсом. Использование sqlite3_enable_load_extension() нужно избегать. Это будет сохранять функцию SQL load_extension() отключенной и препятствовать тому, чтобы SQL injections имели доступ к возможностям загрузки расширения.

См. также load_extension().

Интерфейс регистрации ошибок

void sqlite3_log(int iErrCode, const char *zFormat, ...);

Интерфейс sqlite3_log() пишет сообщение в журнал ошибок, установленный выбором SQLITE_CONFIG_LOG в sqlite3_config(). Если регистрация позволена, последовательность zFormat и последующие аргументы используются с sqlite3_snprintf(), чтобы произвести последовательность окончательного результата.

sqlite3_log() предназначается для использования расширениями, такими как виртуальные таблицы, функции SQL и сопоставления. В то время как нет ничего, чтобы препятствовать запросам вызвать sqlite3_log(), это неправильно.

Строка zFormat не должна быть NULL.

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

Найдите следующий подготовленный запрос

sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);

Этот интерфейс возвращает указатель на следующий подготовленный запрос после pStmt, связанный с соединением с базой данных pDb. Если pStmt = NULL, этот интерфейс возвращает указатель на первый подготовленный запрос, связанный с соединением с базой данных pDb. Если никакой подготовленный запрос не удовлетворяет условиям, он возвращает NULL.

Указатель соединения с базой данных D в sqlite3_next_stmt(D,S) должен относиться к открытому соединению с базой данных и в особенности не должен быть NULL.

Перегрузите функцию для виртуальной таблицы

int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);

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

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

Отзывы прогресса запроса

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

sqlite3_progress_handler(D,N,X,P) заставляет функцию обратного вызова X вызываться периодически во время длительных запросов к sqlite3_step() и sqlite3_prepare() и подобным для соединения с базой данных D. Использование в качестве примера для этого интерфейса должно сохранять GUI обновленным во время выполнения больших запросов.

Через параметр P передают единственный параметр к функции обратного вызова X. Параметр N является приблизительным количеством инструкций по виртуальной машине, которые оценены между последовательными вызовами отзыва X. Если N меньше, чем один, тогда обработчик прогресса выключен.

Только единственный обработчик прогресса может быть определен на связь для каждой базы данных, создание нового обработчика прогресса отменяет старый. Установка параметра X в NULL выключает обработчик прогресса. Обработчик прогресса также выключен, установив N к значению меньше, чем 1.

Если отзыв прогресса вернет ненулевое значение, операция прервана. Эта функция может быть использована, чтобы осуществить кнопку "Cancel" в диалоговом окне прогресса GUI.

Отзыв обработчика прогресса не должен делать ничего, что изменит соединение с базой данных, которое вызвало обработчик прогресса. Обратите внимание на то, что sqlite3_prepare_v2() и sqlite3_step() изменяют их соединения с базой данных.

Отзыв обработчика прогресса был бы первоначально только вызван от байт-кода. Это все еще могло бы быть вызвано во время sqlite3_prepare() и подобного, потому что тот установленный порядок мог бы вызвать переразбор схемы, которая включает управление байт-кодом. Однако, начиная с версии SQLite version 3.41.0, отзыв обработчика прогресса мог бы также быть вызван непосредственно от sqlite3_prepare(), анализируя и производя код для сложных запросов.

Генератор псевдослучайного числа

void sqlite3_randomness(int N, void *P);

SQLite содержит высококачественный генератор псевдослучайного числа (PRNG), используемый, чтобы выбрать случайный ROWID, вставляя новые записи в таблицу, которая уже использует самый большой ROWID. PRNG также используется для встроенных SQL-функций random() и randomblob(). Этот интерфейс позволяет запросам получить доступ к тому же самому PRNG для других целей.

Запрос сохранит N байт хаотичности в буфер P. Параметр P может быть NULL.

Если это ранее не вызвали или если у предыдущего вызова был N меньше, чем один или NULL для P, PRNG выобран, используя хаотичность, полученную из метода xRandomness объекта sqlite3_vfs по умолчанию. Если у предыдущего вызова N = 1 или больше и не-NULL P, тогда псевдохаотичность произведена внутренне и без обращения к sqlite3_vfs xRandomness.

Попытайтесь освободить память кучи

int sqlite3_release_memory(int);

sqlite3_release_memory() пытается освободить N байт памяти кучи, освобождая несущественные выделения памяти, проведенные библиотекой базы данных. Ранее кэшированные страницы базы данных, чтобы улучшить работу, это пример несущественной памяти. sqlite3_release_memory() возвращает число байтов, на самом деле освобожденных, что могло бы быть более или менее, чем сумма, которую требуют. sqlite3_release_memory() вернет 0, если SQLite не собран с SQLITE_ENABLE_MEMORY_MANAGEMENT.

См. также: sqlite3_db_release_memory()

Перезагрузите подготовленный объект запроса

int sqlite3_reset(sqlite3_stmt *pStmt);

Функцию sqlite3_reset() вызывают, чтобы перезагрузить подготовленный объект назад к его начальному состоянию, готовому быть повторно выполненным. Любые переменные SQL-оператора, у которых были значения, связанные с ними, используя sqlite3_bind_*() API, сохраняют свои значения. Используйте sqlite3_clear_bindings(), чтобы перезагрузить привязки.

sqlite3_reset(S) перезагружает подготовленный запрос S назад к началу его программы.

Код возврата от sqlite3_reset(S) указывает действительно ли предыдущая оценка подготовленного запроса S закончена успешно. Если к sqlite3_step(S) прежде никогда не обращались на S или если sqlite3_step(S) не вызвали, начиная с предыдущего обращения к to sqlite3_reset(S), то sqlite3_reset(S) вернет SQLITE_OK.

Если новый запрос к sqlite3_step(S) для подготовленного запроса S указал на ошибку, то sqlite3_reset(S) возвращает соответствующий код ошибки. sqlite3_reset(S) мог бы также возвратить код ошибки, если бы не было никаких предшествующих ошибок, но процесс сброса подготовленного запроса вызвал новую ошибку. Например, если INSERT с RETURNING выполнен только один раз, запрос sqlite3_step(S) мог бы возвратить SQLITE_ROW, но полный запрос мог бы все еще потерпеть неудачу, и sqlite3_reset(S) мог бы возвратить SQLITE_BUSY, если ограничения блокировки препятствуют тому, чтобы изменение базы данных передалось. Поэтому важно, чтобы запросы проверили код возврата от sqlite3_reset(S), даже если никакой предшествующий запрос к sqlite3_step(S) не указал на проблему.

sqlite3_reset(S) не изменяет значения никаких привязок в подготовленном запросе S.

Перезагрузите автоматическую загрузку дополнений

void sqlite3_reset_auto_extension(void);

Этот интерфейс отключает все автоматические расширения, ранее зарегистрированные через sqlite3_auto_extension().

Урегулирование подтипа функции SQL

void sqlite3_result_subtype(sqlite3_context*,unsigned int);

sqlite3_result_subtype(C,T) приводит подтип результата из SQL-функции с sqlite3_context C в значение T. Только нижние 8 битов подтипа T сохранены в текущих версиях SQLite, от битов высшего порядка отказываются. Число битов подтипа, сохраненных SQLite, могло бы увеличиться в будущих выпусках SQLite.

Преобразуйте в последовательную форму базу данных

unsigned char *sqlite3_serialize(
  sqlite3 *db,           /* The database connection */
  const char *zSchema,   /* Which DB to serialize. ex: "main", "temp", ... */
  sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
  unsigned int mFlags    /* Zero or more SQLITE_SERIALIZE_* flags */
);

sqlite3_serialize(D,S,P,F) возвращает указатель на память, которая является преобразованием в последовательную форму базы данных S по соединению с базой данных D. Если P не NULL, то размер базы данных в байтах вписывают в *P.

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

Обычный случай, что sqlite3_serialize() копирует преобразование в последовательную форму базы данных в память, полученную из sqlite3_malloc64(), и возвращает указатель на ту память. Вызывающий ответственен за освобождение возвращенного значения, чтобы избежать утечки памяти. Однако, если аргумент F содержит бит SQLITE_SERIALIZE_NOCOPY, то никакие выделения памяти не сделаны, и sqlite3_serialize() возвратит указатель на смежное представление памяти базы данных, которую SQLite в настоящее время использует для той базы данных или NULL, если никакое такое смежное представление памяти базы данных не существует. Смежное представление памяти базы данных обычно будет существовать только, если был предшествующий запрос sqlite3_deserialize(D,S,...) с теми же самыми D и S. Размер базы данных вписывают в *P, даже если бит SQLITE_SERIALIZE_NOCOPY установлен, но никакая смежная копия базы данных не существует.

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

Вызов sqlite3_serialize(D,S,P,F) вернет NULL, даже если бы бит SQLITE_SERIALIZE_NOCOPY опущен в аргументе F, если ошибка распределения памяти происходит.

Этот интерфейс опущен, если SQLite собран с выбором SQLITE_OMIT_DESERIALIZE.

Установите значение Last Insert Rowid

void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);

sqlite3_set_last_insert_rowid(D, R) позволяет установить значение, возвращенное sqlite3_last_insert_rowid(D), в R не вставляя строку в базу данных.

Приостановите выполнение в течение короткого времени

int sqlite3_sleep(int);

sqlite3_sleep() заставляет текущий поток приостанавливать выполнение по крайней мере на число миллисекунд, определенных в его параметре.

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

SQLite осуществляет этот интерфейс, называя xSleep() методом умолчания объекта sqlite3_vfs. Если метод xSleep() в VFS не осуществляется правильно или не осуществляется вообще, то поведение sqlite3_sleep() может отклониться от описания в предыдущих параграфах.

Если отрицательный аргумент передается sqlite3_sleep(), результаты варьируются VFS и операционной системой. Некоторая система рассматривает отрицательный аргумент как инструкцию спать всегда. Другие понимают, что это означает не спать вообще. В версии 3.42.0 SQLite и позже отрицательный аргумент, переданный в sqlite3_sleep(), изменяется на ноль, прежде чем это будет передано в метод xSleep VFS.

Сравните возрасты двух обработчиков образа

int sqlite3_snapshot_cmp(sqlite3_snapshot *p1, sqlite3_snapshot *p2);

sqlite3_snapshot_cmp(P1, P2) используется, чтобы сравнить возрасты двух действительных обработчиков образов.

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

Кроме того, результат сравнения действителен только, если оба обработчика были получены, вызывая sqlite3_snapshot_get() с прошлого раза, когда wal-файл был удален. wal-файл удален, когда база данных изменяется на режим обратной перемотки или когда число клиентов базы данных опускается до нуля. Если любой обработчик был получен, прежде чем wal-файл был в последний раз удален, значение, возвращенное этой функцией, не определено.

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

Этот интерфейс доступен только, если SQLite собран с выбором SQLITE_ENABLE_SNAPSHOT.

Уничтожьте образ

void sqlite3_snapshot_free(sqlite3_snapshot*);

sqlite3_snapshot_free(P) разрушает sqlite3_snapshot P. Приложение должно в конечном счете освободить каждый объект sqlite3_snapshot, чтобы избежать утечки памяти.

sqlite3_snapshot_free() доступен только, когда использован выбор времени компиляции SQLITE_ENABLE_SNAPSHOT.

Сделайте запись образа базы данных

int sqlite3_snapshot_get(sqlite3 *db, const char *zSchema,
                         sqlite3_snapshot **ppSnapshot);

sqlite3_snapshot_get(D,S,P) пытается заставить новый объект sqlite3_snapshot сделать запись текущего состояния схемы S в соединении с базой данных D. При успехе sqlite3_snapshot_get(D,S,P) пишет указатель на недавно созданный объект sqlite3_snapshot в *P и вернет SQLITE_OK. Если нет уже прочитанной транзакции, открытой на схеме S, когда эта функция вызвана, она открыта автоматически.

Следующее должно быть верным для этой функции, чтобы она работала. Если какое-либо из следующих заявлений ложно, когда вызывают sqlite3_snapshot_get(), SQLITE_ERROR возвращен. Окончательное значение *P не определено в этом случае.

• Обработчик базы данных не должен быть в autocommit mode.

• Схема S соединения с базой данных D должна быть базой данных в режиме WAL.

• Не должно быть транзакции записи, открытой на схеме S соединения с базой данных D.

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

Эта функция может также возвратить SQLITE_NOMEM. Если это вызывают с обработчиком базы данных в режиме autocommit, но происходит сбой по некоторой другой причине, открыта ли транзакция на схеме S, не определено.

Объект sqlite3_snapshot, возвращенный от успешного вызова sqlite3_snapshot_get(), должен быть освобожден, используя sqlite3_snapshot_free(), чтобы избежать утечки памяти.

sqlite3_snapshot_get() доступен только когда применен выбор времени компиляции SQLITE_ENABLE_SNAPSHOT.

Начните транзакцию чтения на историческом образе

int sqlite3_snapshot_open(sqlite3 *db, const char *zSchema,
                          sqlite3_snapshot *pSnapshot);

sqlite3_snapshot_open(D,S,P) начинает новую или модернизирует существующую транзакцию для схемы S соединения с базой данных D таким образом, что транзакция относится к историческому образу P, а не к новому изменению базы данных. sqlite3_snapshot_open() вернет SQLITE_OK при успехе или соответствующий код ошибки.

Чтобы добиться успеха, соединение с базой данных не должно быть в режиме autocommit, когда вызван sqlite3_snapshot_open(D,S,P). Если уже есть транзакция, открытая на схеме S, то у обработчика базы данных не должно быть активных запросов (операторы SELECT, которые были переданы to sqlite3_step(), но не sqlite3_reset() или sqlite3_finalize()). SQLITE_ERROR возвращен, если условие нарушено, схема S не существует или если объект образа недействителен.

Вызов sqlite3_snapshot_open() не откроется, если указанный образ был переписан контрольной точкой. В этом случае возвращен SQLITE_ERROR_SNAPSHOT.

Если уже есть транзакция, открытая, когда эта функция вызвана, то та же самая транзакция остается открытой (на том же самом образе базы данных), если возвращено SQLITE_ERROR, SQLITE_BUSY или SQLITE_ERROR_SNAPSHOT. Если другой код ошибки, например, SQLITE_PROTOCOL или SQLITE_IOERR возвращены, то конечное состояние транзакции не определено. Если вернется SQLITE_OK, транзакция теперь открыта на снимке базы данных P.

Вызов sqlite3_snapshot_open(D,S,P) потерпит неудачу, если соединение с базой данных D не будет знать, что файл базы данных для схемы S находится в режиме WAL. Соединение с базой данных не могло бы знать, что файл базы данных находится в режиме WAL, если не было никакого предшествующего I/O на том соединении с базой данных или если база данных попала в режим WAL после нового I/O на соединении с базой данных. Выполните "PRAGMA application_id" для недавно открытого соединения с базой данных, чтобы применять образы.

sqlite3_snapshot_open() работает только при использовании опции времени компиляции SQLITE_ENABLE_SNAPSHOT.

Возвратите образы из файла wal

int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);

Если файл WAL останется на диске после закрытия всех соединений с базой данных (с помощью SQLITE_FCNTL_PERSIST_WAL file control или потому что последний процесс, который работал с базой данных, не вызвал sqlite3_close()), новая связь впоследствии открыта на той базе данных, интерфейс sqlite3_snapshot_open() будет в состоянии открыть последнюю транзакцию, добавленную к файлу WAL, даже при том, что файл WAL содержит другие действительные транзакции.

Эта функция пытается просмотреть файл WAL, связанный с базой данных zDb, обрабатываемой db, и делают все действительные образы доступными для sqlite3_snapshot_open(). Происходит ошибка, если уже есть транзакция, открытая на базе данных, или если база данных это не база данных режима WAL.

SQLITE_OK возвращен в случае успеха, иначе код ошибки.

Этот интерфейс доступен только, если SQLite собран с выбором SQLITE_ENABLE_SNAPSHOT.

Мягкий интерфейс предела кучи (устаревший)

void sqlite3_soft_heap_limit(int N);

Это устаревшая версия sqlite3_soft_heap_limit64(). Обеспечивается только для исторической совместимости. Все новые запросы должны использовать sqlite3_soft_heap_limit64().

Оцените SQL-оператор

int sqlite3_step(sqlite3_stmt*);

После того, как подготовленный запрос был подготовлен, используя любой вызов из sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(), sqlite3_prepare16_v3() или один из старых интерфейсов sqlite3_prepare() или sqlite3_prepare16(), эта функция должна быть вызвана один или несколько раз, чтобы оценить запрос.

Детали поведения sqlite3_step() зависят от того, был ли запрос подготовлен, используя более новый интерфейс "vX", sqlite3_prepare_v3(), sqlite3_prepare_v2(), sqlite3_prepare16_v3(), sqlite3_prepare16_v2() или старые интерфейсы sqlite3_prepare() и sqlite3_prepare16(). Использование нового интерфейса "vX" рекомендуется для новых запросов, но устаревший интерфейс продолжит поддерживаться.

В устаревшем интерфейсе возвращаемое значение будет SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR или SQLITE_MISUSE. С интерфейсом "v2" любой из других кодов результата или расширенных кодов результата мог бы быть возвращен.

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

SQLITE_DONE означает, что запрос закончил выполняться успешно. sqlite3_step() нельзя вызвать снова на этой виртуальной машине без предварительного sqlite3_reset(), чтобы перезагрузить виртуальную машину назад к ее начальному состоянию.

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

SQLITE_ERROR означает, что произошла ошибка периода выполнения (такая как ограничительное нарушение). sqlite3_step() нельзя вызвать снова на VM. Больше информации может быть найдено, вызывая sqlite3_errmsg(). С устаревшим интерфейсом более определенный код ошибки (например, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT и т.д.) может быть получен, вызывая sqlite3_reset() на подготовленном запросе. В интерфейсе "v2" более определенный код ошибки возвращен непосредственно sqlite3_step().

SQLITE_MISUSE означает, что это вызвали неуместно. Возможно, это вызвали на подготовленном запросе, который был уже финализирован, или на том, который ранее возвратил SQLITE_ERROR или SQLITE_DONE. Или могло иметь место, что то же самое соединение с базой данных используется двумя или больше потоками одновременно.

Для всех версий SQLite до и включая 3.6.23.1 требовался запрос sqlite3_reset() после того, как sqlite3_step() вернул что-то кроме SQLITE_ROW перед любым последующим sqlite3_step(). Отказ перезагрузить подготовленный запрос, используя sqlite3_reset() привел бы к возвращению SQLITE_MISUSE из sqlite3_step(). Но после version 3.6.23.1 (2010-03-26 sqlite3_step() начал вызывать sqlite3_reset() автоматически при этом обстоятельстве вместо того, чтобы возвратить SQLITE_MISUSE. Это не считают разрывом совместимости, потому что любое применение, которое когда-либо получает ошибку SQLITE_MISUSE, сломано по определению. Выбор времени компиляции SQLITE_OMIT_AUTORESET может использоваться, чтобы восстановить устаревшее поведение.

В устаревшем интерфейсе sqlite3_step() API всегда возвращает универсальный код ошибки SQLITE_ERROR после любой ошибки, кроме SQLITE_BUSY и SQLITE_MISUSE. Необходимо вызвать sqlite3_reset() или sqlite3_finalize(), чтобы найти один из определенных кодов ошибки, которые лучше описывают ошибку. Мы признаем, что это глупый дизайн. Проблема была решена с интерфейсом "v2". Если вы готовите все свои SQL-операторы, используя sqlite3_prepare_v3(), sqlite3_prepare_v2(), sqlite3_prepare16_v2() или sqlite3_prepare16_v3() вместо sqlite3_prepare() и sqlite3_prepare16(), то более определенные коды ошибок возвращены непосредственно sqlite3_step(). Использование интерфейсов "vX" рекомендуется.

Определите, был ли подготовленный запрос перезагружен

int sqlite3_stmt_busy(sqlite3_stmt*);

sqlite3_stmt_busy(S) вернет true (не 0), если подготовленный запрос S выполнен хотя бы раз через sqlite3_step(S), но завершен (вернул SQLITE_DONE из sqlite3_step(S)) и не сброшен, используя sqlite3_reset(S). sqlite3_stmt_busy(S) вернет false, если S = NULL. Если S не NULL и не является указателем на действительный подготовленный запрос, то поведение не определено и вероятно нежелательно.

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

Измените настройки EXPLAIN для подготовленного запроса

int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);

sqlite3_stmt_explain(S,E) изменяет настройки EXPLAIN для setting for подготовленного запроса S. Если E=0, S становится нормальным подготовленным запросом. Если E = 1, S ведет себя, как будто его код на SQL начался с "EXPLAIN". Если E = 2, S ведет себя, как будто его код на SQL начался с "EXPLAIN QUERY PLAN".

Вызов sqlite3_stmt_explain(S,E) могло бы заставить S быть повторно подготовленным. SQLite пытается избежать повторной подготовки, но это могло бы быть необходимым на первом переходе в режим EXPLAIN или EXPLAIN QUERY PLAN.

Из-за потенциальной потребности повторно подготовить запрос к sqlite3_stmt_explain(S,E) потерпит неудачу с SQLITE_ERROR, если S не может быть повторно подготовлен, потому что это было создано, используя sqlite3_prepare() вместо более нового sqlite3_prepare_v2() или sqlite3_prepare_v3() и следовательно не имеет никакого сохраненного кода на SQL, с которым можно повторно подготовиться.

Изменение настройки explain для подготовленного запроса не изменяет оригинальный код на SQL для запроса. Следовательно, если код на SQL первоначально начался с EXPLAIN или EXPLAIN QUERY PLAN, но sqlite3_stmt_explain(S,0) вызывают, чтобы преобразовать запрос в обычный, ключевые слова EXPLAIN или EXPLAIN QUERY PLAN все еще появятся в выводе sqlite3_sql(S) даже при том, что запрос теперь действует как нормальный SQL-оператор.

Это вернет SQLITE_OK, если режим explain успешно изменяется или код ошибки, если режим не мог быть изменен. Режим explain не может быть изменен в то время, как запрос активен. Следовательно, хорошая практика, чтобы вызвать sqlite3_reset(S) немедленно до запроса sqlite3_stmt_explain(S,E).

Запросите настройку EXPLAIN для подготовленного запроса

int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);

sqlite3_stmt_isexplain(S) вернет 1, если подготовленный запрос S это запрос EXPLAIN, 2, если запрос S это EXPLAIN QUERY PLAN. sqlite3_stmt_isexplain(S) вернет 0, если S обычный запрос или NULL.

Определите, пишет ли SQL-оператор базу данных

int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);

sqlite3_stmt_readonly(X) возвращает true (не 0), если и только если подготовленный запрос X не вносит прямых изменений в содержание файла базы данных.

Обратите внимание на то, что определенные приложением функции SQL или виртуальные таблицы могли бы изменить базу данных косвенно как побочный эффект. Например, если приложение определяет функцию "eval()", которая вызывает sqlite3_exec(), следующий SQL-оператор изменил бы файл базы данных через побочные эффекты:

SELECT eval('DELETE FROM t1') FROM t2;

Но потому что SELECT не изменяет файл базы данных непосредственно, sqlite3_stmt_readonly() все еще возвратил бы true.

Команды управления транзакциями, такие как BEGIN, COMMIT, ROLLBACK, SAVEPOINT и RELEASE, заставляют sqlite3_stmt_readonly() вернуть true, так как сами запросы на самом деле не изменяют базу данных, а скорее они управляют выбором времени, когда другие запросы изменяют базу данных. ATTACH и DETACH также заставляют sqlite3_stmt_readonly() вернуть true: они изменяют конфигурацию соединения с базой данных, но не вносят изменения в содержание файлов базы данных на диске. sqlite3_stmt_readonly() вернет true для BEGIN, поскольку BEGIN устанавливает внутренние флаги, но BEGIN IMMEDIATE и BEGIN EXCLUSIVE действительно касаются базы данных, значит для них sqlite3_stmt_readonly() вернет false.

Это вернет false, если есть возможность, что запрос мог бы изменить файл базы данных. Возврат false не гарантирует, что запрос изменит файл базы данных. Например, у запроса UPDATE мог бы быть оператор WHERE, который делает его нерабочим, но результат sqlite3_stmt_readonly() все еще был бы false. Точно так же CREATE TABLE IF NOT EXISTS является только для чтения, когда таблица уже существует, но sqlite3_stmt_readonly() вернет false.

Если подготовленный запрос X это EXPLAIN или EXPLAIN QUERY PLAN, sqlite3_stmt_readonly(X) вернет то же самое значение, как будто префикс EXPLAIN или EXPLAIN QUERY PLAN пропущен.

Обнуляет все счетчики событий

void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);

Обнуляет все счетчики событий, связанных с sqlite3_stmt_scanstatus().

API доступен только, если библиотека строится с символом препроцессора SQLITE_ENABLE_STMT_SCANSTATUS.

Подготовленный статус запроса

int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);

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

Этот интерфейс используется, чтобы получить и перезагрузить значения из подготовленного запроса. Первый аргумент это подготовленный объект запроса, который будет опрошен. Второй аргумент это код целого числа для определенного счетчика SQLITE_STMTSTATUS. Текущее значение требуемого счетчика возвращено. Если resetFlg = true, счетчик перезагружается к нолю после этого интерфейсного вызова.

См. также: sqlite3_status() и sqlite3_db_status().

Завершите динамическую последовательность

char *sqlite3_str_finish(sqlite3_str*);

sqlite3_str_finish(X) разрушает объект sqlite3_str X и возвращает указатель на буфер памяти, полученный из sqlite3_malloc64(), который содержит построенную последовательность. Вызывающее приложение должно передать возвращенное значение sqlite3_free(), чтобы избежать утечки памяти. sqlite3_str_finish(X) может возвратить NULL, если с какими-либо ошибками столкнулись во время создания последовательности. sqlite3_str_finish(X) также возвратит NULL, если последовательность в sqlite3_str X имеет нулевую длину.

Создайте новый динамический объект последовательности

sqlite3_str *sqlite3_str_new(sqlite3*);

sqlite3_str_new(D) ассигнует и инициализирует новый объект sqlite3_str. Чтобы избежать утечек памяти, объект, возвращенный sqlite3_str_new(), должен быть освобожден последующим запросом к sqlite3_str_finish(X).

sqlite3_str_new(D) всегда возвращает указатель на действительный объект sqlite3_str, хотя в случае ошибки памяти возвращенный объект мог бы быть специальным единичным предметом, который тихо отклонит новый текст, всегда возвратит SQLITE_NOMEM из sqlite3_str_errcode(), всегда возвратит 0 для sqlite3_str_length() и всегда возвратит NULL из sqlite3_str_finish(X). Всегда безопасно использовать значение, возвращенное sqlite3_str_new(D) как параметр sqlite3_str к любому из других методов sqlite3_str.

Параметр D для sqlite3_str_new(D) может быть NULL. Если параметром D в sqlite3_str_new(D) не NULL, то максимальная длина последовательности, содержавшейся в объекте sqlite3_str, будет установлена значением для sqlite3_limit(D, SQLITE_LIMIT_LENGTH) вместо SQLITE_MAX_LENGTH.

Соответствие строки шаблону

int sqlite3_strglob(const char *zGlob, const char *zStr);

sqlite3_strglob(P,X) возвращает ноль если и только если последовательность X соответствует GLOB шаблону P. Определение шаблона GLOB, используемого в sqlite3_strglob(P,X) аналогично оператору "X GLOB P" в диалекте SQL, понятом под SQLite. sqlite3_strglob(P,X) чувствительная к регистру.

Обратите внимание на то, что это возвращает ноль при соответствии, но не ноль, если последовательности не соответствуют, аналогично sqlite3_stricmp() и sqlite3_strnicmp().

См. также: sqlite3_strlike().

Строка соответствует LIKE

int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);

sqlite3_strlike(P,X,E) возвращает ноль если и только если последовательность X соответствует LIKE шаблону P с символом ESC E. Определение сопоставления с образцом LIKE, используемого в sqlite3_strlike(P,X,E), аналогично оператору "X LIKE P ESCAPE E" в SQLite. Для "X LIKE P" без пункта ESCAPE, параметр E в sqlite3_strlike(P,X,E) = 0. Как с LIKE, sqlite3_strlike(P,X,E) функция нечувствительна к регистру: эквивалентны верхний и нижний регистры, знаки ASCII соответствуют друг другу.

sqlite3_strlike(P,X,E) сравнивает и Unicode, хотя только ASCII не зависят от регистра.

Обратите внимание на то, что это возвращает ноль на соответствии и не 0, если последовательности не соответствуют, аналогично sqlite3_stricmp() и sqlite3_strnicmp().

См. также: sqlite3_strglob().

Код системной ошибки низкого уровня

int sqlite3_system_errno(sqlite3*);

Пытается возвратить основной код ошибки операционной системы или код ошибки, который вызвал новую ошибку I/O или отказ открыть файл. Возвращаемое значение зависимо от операционной системы. Например, на системах Unix после sqlite3_open_v2() с SQLITE_CANTOPEN этот интерфейс можно было вызвать, чтобы возвратить основной "errno", который вызвал проблему, такую как ENOSPC, EAUTH, EISDIR или нечто подобное.

Метаданные о колонке таблицы

int sqlite3_table_column_metadata(
  sqlite3 *db,                /* Connection handle */
  const char *zDbName,        /* Database name or NULL */
  const char *zTableName,     /* Table name */
  const char *zColumnName,    /* Column name */
  char const **pzDataType,    /* OUTPUT: Declared data type */
  char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
  int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
  int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
  int *pAutoinc               /* OUTPUT: True if column is auto-increment */
);

sqlite3_table_column_metadata(X,D,T,C,....) вернет информацию о колонке C таблицы T в базе данных D по соединению с базой данных X. sqlite3_table_column_metadata() возвращает SQLITE_OK и заполняет не-NULL указатели в заключительных пяти параметрах соответствующими значениями, если указанная колонка существует. sqlite3_table_column_metadata() вернет SQLITE_ERROR, если указанная колонка не существует. Если параметр имени столбца в sqlite3_table_column_metadata() = NULL, это просто проверяет на существование таблицы и возвращает SQLITE_OK, если таблица есть и SQLITE_ERROR, если нет. Если параметр имени таблицы T в вызове sqlite3_table_column_metadata(X,D,T,C,...) = NULL, результатом будет неопределенное поведение.

Колонка определяется вторыми, третьими и четвертыми параметрами функции. Второй параметр это название базы данных ("main", "temp" или приложенная база данных), содержащей указанную таблицу, или NULL. Если это NULL, то все приложенные базы данных проверены на таблицу, используя тот же самый алгоритм, используемый ядром базы данных, чтобы разрешить неквалифицированные ссылки на таблицу.

Третий и четвертый параметры таблица и имя требуемого столбца, соответственно.

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

Параметр	Вывод Тип	Описание
5	const char*	Тип данных
6	const char*	Название сортирующей последовательности по умолчанию
7	int	True, если у колонки есть ограничение NOT NULL
8	int	True, если колонка это часть PRIMARY KEY
9	int	True, если колонка это AUTOINCREMENT

Память, на которую указывают указатели, возвращенные для типа декларации и сортирующей последовательности, действительна до следующего обращения к любой API-функции SQLite.

Если указанная таблица на самом деле представление, возвращается код ошибки.

Если указанная колонка "rowid", "oid" или "_rowid_", таблица не является WITHOUT ROWID и столбец, которым была явно объявлена колонка INTEGER PRIMARY KEY, то параметры вывода устанавливаются для явно заявленной колонки. Если нет никакого столбца INTEGER PRIMARY KEY, вывод для rowid установлен следующим образом:

data type: "INTEGER"
collation sequence: "BINARY"
not null: 0
primary key: 1
auto increment: 0

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

Тестирование интерфейса

int sqlite3_test_control(int op, ...);

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

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

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

Тест, чтобы видеть, ориентирована ли библиотека на многопоточное исполнение

int sqlite3_threadsafe(void);

sqlite3_threadsafe() возвращает ноль если и только если SQLite был собран с кодом mutexing, опущенным из-за выбора времени компиляции SQLITE_THREADSAFE = 0.

SQLite может быть собран с или без mutexes. Когда макрос SQLITE_THREADSAFE препроцессора C равняется 1 или 2, mutexes позволены, а SQLite ориентирован на многопоточное исполнение. Когда макрос SQLITE_THREADSAFE = 0, mutexes опущены. Без mutexes небезопасно использовать SQLite одновременно больше, чем от одного потока.

Предоставление возможности mutexes подвергается измеримой потере производительности. Таким образом, если скорость имеет предельное значение, имеет смысл отключать mutexes. Но для максимальной безопасности, должен быть позволен mutexes. Поведение по умолчанию: включены mutexes.

Этот интерфейс может использоваться, чтобы удостовериться, что версия SQLite была собрана с желаемым значением макроса SQLITE_THREADSAFE.

Этот интерфейс сообщает только о значении флага времени компиляции SQLITE_THREADSAFE. Если SQLite собран с SQLITE_THREADSAFE=1 или =2, тогда mutexes позволены по умолчанию, но могут быть полностью или частично отключены, используя запрос sqlite3_config() с параметрами SQLITE_CONFIG_SINGLETHREAD , SQLITE_CONFIG_MULTITHREAD или SQLITE_CONFIG_SERIALIZED. Возвращаемое значение sqlite3_threadsafe() показывает только значение времени компиляции, но не любые изменения во время выполнения, сделанные sqlite3_config(). Другими словами, возвращаемое значение sqlite3_threadsafe() неизменно вызовами sqlite3_config().

См. здесь для подробностей.

Перехват трассировки SQL

int sqlite3_trace_v2(sqlite3*, unsigned uMask,
                     int(*xCallback)(unsigned,void*,void*,void*),void *pCtx);

sqlite3_trace_v2(D,M,X,P) регистрирует функцию обратного вызова трассировки X для соединения с базой данных D, используя маску M и указатель контекста P. Если отзыв X = NULL или если M = 0, то отслеживание отключено. Аргумент M должен быть комбинацией OR из 0 или более констант SQLITE_TRACE.

Каждый запрос к sqlite3_trace(D,X,P) или sqlite3_trace_v2(D,M,X,P) отменяет все предшествующие вызовы sqlite3_trace(D,X,P) или sqlite3_trace_v2(D,M,X,P) для соединения с базой данных D. У каждого соединения с базой данных может быть самое большее один отзыв трассировки.

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

Отзыв вызван с четырьмя аргументами: callback(T,C,P,X). Аргумент T это одна из констант SQLITE_TRACE, чтобы указать, почему отзыв был вызван. Аргумент C это копия указателя контекста. Аргументы P и X это указатели, значения которых зависят от T.

sqlite3_trace_v2() предназначается, чтобы заменить устаревшие интерфейсы sqlite3_trace() и sqlite3_profile().

Определите операционное состояние БД-

int sqlite3_txn_state(sqlite3*,const char *zSchema);

sqlite3_txn_state(D,S) возвращает текущее операционное состояние схемы S в соединении с базой данных D. Если S = NULL, то самое высокое операционное состояние любой схемы на соединении с базой данных D возвращено. Операционные состояния (в порядке от самого низкого к самому высокому):

0. SQLITE_TXN_NONE
1. SQLITE_TXN_READ
2. SQLITE_TXN_WRITE

Разблокировать уведомление

int sqlite3_unlock_notify(
  sqlite3 *pBlocked,                          /* Waiting connection */
  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
  void *pNotifyArg                            /* Argument to pass to xNotify */
);

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

Блокировки общего кэша выпущены, когда соединение с базой данных завершает свою текущую транзакцию.

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

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

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

Может быть самое большее один отзыв, зарегистрированный заблокированной связью. Если sqlite3_unlock_notify() вызывают, когда у заблокированной связи уже есть зарегистрированный отзыв, то новый отзыв заменяет старый. Если sqlite3_unlock_notify() вызывают с NULL как его второй аргумент, то любой существующий отзыв уведомления отменяется. Отзыв может также быть отменен, закрыв заблокированную связь, используя sqlite3_close().

Если приложение вызывает какие-либо функции API sqlite3_xxx, из отзыва уведомления, катастрофа или мертвая блокировка могут быть результатом.

Если мертвая блокировка не обнаружена (см. ниже), sqlite3_unlock_notify() всегда вернет SQLITE_OK.

Детали вызова отзыва

Когда отзыв зарегистрирован, применение обеспечивает единственный указатель void*, который передается к отзыву, когда это вызвано. Однако, сигнатура функции обратного вызова позволяет SQLite передавать ему множество указателей контекста void*. Первый аргумент, переданный отзыву это указатель на множество указателей void*, вторым является количество записей во множестве.

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

Обнаружение мертвой блокировки

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

Чтобы избежать этого сценария, sqlite3_unlock_notify() выполняет обнаружение мертвой блокировки. Если бы данный запрос к sqlite3_unlock_notify() поместил бы систему в заведенное в тупик состояние, то SQLITE_LOCKED возвращен, и отзыв не регистрируют. Система, как говорят, находится в заведенном в тупик состоянии, если связь A зарегистрировала отзыв относительно заключения транзакции Б связи, и связь B самостоятельно зарегистрировала отзыв, когда транзакция А связи завершена. Косвенная мертвая блокировка также обнаружена, таким образом, система также считается заведенной в тупик, если связь B зарегистрировала отзыв уведомления относительно заключения транзакции C, где связь C ждет связь A. Любое количество уровней абстракции позволено.

Исключение "DROP TABLE"

Когда sqlite3_step() вовзращает SQLITE_LOCKED, почти всегда уместно вызвать sqlite3_unlock_notify(). Есть, однако, одно исключение. Выполняя запрос "DROP TABLE" или "DROP INDEX", SQLite проверяет, есть ли какие-либо в настоящее время выполняющиеся операторы SELECT, которые принадлежат той же самой связи. Если есть, SQLITE_LOCKED возвращен. В этом случае нет никакой "связи блокирования", таким образом, результаты вызова sqlite3_unlock_notify() поступают немедленно. Если приложение повторно делает попытку запроса "DROP TABLE" или "DROP INDEX", бесконечный цикл мог бы быть результатом.

Один обход этой проблемы состоит в том, чтобы проверить расширенный код ошибки, возвращенный sqlite3_step(). Если есть связь блокирования, то расширенный код ошибки установлен в SQLITE_LOCKED_SHAREDCACHE. Иначе, в специальном случае "DROP TABLE/INDEX" расширенный код ошибки это просто SQLITE_LOCKED.

Отзывы уведомления об изменении данных

void *sqlite3_update_hook(sqlite3*,
                          void(*)(void *,int ,char const *,char const *,
                          sqlite3_int64), void*);

sqlite3_update_hook() регистрирует функцию обратного вызова в соединении с базой данных, определенном первым аргументом, которая будет вызвана каждый раз, когда строка обновлена, вставлена или удалена в таблице rowid . Любой отзыв, установленный предыдущим запросом к этой функции для того же самого соединения с базой данных, отвергнут.

Второй аргумент это указатель на функцию, чтобы вызвать, когда строка обновлена, вставлена или удалена в таблице rowid. Первый аргумент отзыва это копия третьего аргумента sqlite3_update_hook(). Второй аргумент отзыва один из SQLITE_INSERT, SQLITE_DELETE или SQLITE_UPDATE, в зависимости от операции, которая заставила отзыв быть вызванным. Третий и четвертый аргументы отзыва содержат указатели на имя базы данных и имя таблицы, содержащей затронутую строку. Заключительный параметр отзыва rowid строки. В случае обновления это rowid после того, как обновление произойдет.

Перехватчик обновления не вызван, когда внутренние системные таблицы изменяются (то есть sqlite_sequence). Перехватчик обновления не вызван, когда меняются таблицы WITHOUT ROWID.

В текущем внедрении не вызван перехватчик обновления, когда противоречивые строки удалены из-за ON CONFLICT REPLACE. И при этом перехватчик обновления не вызван, когда строки удалены, используя truncate optimization. Исключения, определенные в этом параграфе, могли бы измениться в будущем выпуске SQLite.

Перехватчик обновления не должен делать ничего, что изменит соединение с базой данных, которое его вызвало. Любые действия, чтобы изменить соединение с базой данных должны быть отсрочены до окончания завершения sqlite3_step(), который вызвал обьновление. Обратите внимание на то, что sqlite3_prepare_v2() и sqlite3_step() изменяют их соединения с базой данных.

sqlite3_update_hook(D,C,P) вернет P от предыдущего запроса к тому же самому соединению с базой данных D или NULL для первого запроса D.

См. также sqlite3_commit_hook(), sqlite3_rollback_hook() и sqlite3_preupdate_hook().

Пользовательские данные для функций

void *sqlite3_user_data(sqlite3_context*);

sqlite3_user_data() возвращает копию указателя, который был параметром pUserData (5-й параметр) в sqlite3_create_function() и sqlite3_create_function16(), который первоначально зарегистрировал определенную приложением функцию.

Это нужно вызвать от того же потока, в котором работает определенная приложением функция.

Сообщите внутренний текст, кодирующем статус объекта sqlite3_value

int sqlite3_value_encoding(sqlite3_value*);

sqlite3_value_encoding(X) вернет SQLITE_UTF8, SQLITE_UTF16BE или SQLITE_UTF16LE, согласно текущему кодированию текста, значение X, предполагая, что X имеет тип TEXT. Если sqlite3_value_type(X) вернет что-то другое, чем SQLITE_TEXT, возвращаемое значение sqlite3_value_encoding(X) бессмысленно. Вызов sqlite3_value_text(X), sqlite3_value_text16(X), sqlite3_value_text16be(X), sqlite3_value_text16le(X), sqlite3_value_bytes(X) или sqlite3_value_bytes16(X) может изменить кодирование значения X и таким образом изменить возврат от последующих вызовов sqlite3_value_encoding(X).

Этот установленный порядок предназначается для использования запросами, которые проверяют внедрение SQLite. Этот установленный порядок справляется о непрозрачном внутреннем состоянии объекта sqlite3_value. Обычные запросы не должны знать внутреннее состояние объекта an sqlite3_value и следовательно не должны использовать этот интерфейс.

Нахождение подтипа значений SQL

unsigned int sqlite3_value_subtype(sqlite3_value*);

sqlite3_value_subtype(V) возвращает подтип для аргумента V SQL-функции, определенной приложением. Информация о подтипе может использоваться, чтобы передать ограниченную сумму контекста от одной функции SQL другой. Используйте sqlite3_result_subtype(), чтобы установить подтип для возвращаемого значения функции SQL.

Определите сопоставление для виртуального ограничения таблицы

const char *sqlite3_vtab_collation(sqlite3_index_info*,int);

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

Первый аргумент должен быть указателем на объект sqlite3_index_info, который является первым параметром метода xBestIndex(). Второй аргумент должен быть индексом в массиве aConstraint[], принадлежащим структуре sqlite3_index_info, переданной xBestIndex.

ВАЖНО: первый параметр должен быть тем же самым указателем, который передается в метод xBestMethod(). Первый параметр может не быть указателем на различный объект sqlite3_index_info.

Возвращаемое значение вычисляется следующим образом:

1. Если ограничение прибывает из выражения оператора Where, которое содержит оператор COLLATE, то название сопоставления, определенного тем, что оператор COLLATE вернет.

2. Если нет никакого оператора COLLATE, но колонка, которая является предметом ограничения, определяет альтернативную последовательность сопоставления с помощью параметра COLLATE в определении столбца в рамках CREATE TABLE, которое было передано sqlite3_declare_vtab(), то название той альтернативной последовательности сопоставления возвращено.

3. Иначе вернется "BINARY".

Виртуальная конфигурация интерфейса таблицы

int sqlite3_vtab_config(sqlite3*, int op, ...);

Эта функция может быть вызвана методом xConnect или xCreate виртуальной таблицы, чтобы сформировать различные аспекты виртуального интерфейса таблицы.

Если этот интерфейс вызван вне контекста метода xConnect или xCreate виртуальной таблицы, поведение не определено.

В вызове sqlite3_vtab_config(D,C,...) параметр D это соединение с базой данных, в котором составляется виртуальная таблица и которое передается как первый аргумент метода xConnect или xCreate, который является вызовом sqlite3_vtab_config(). Параметр C один из параметров конфигурации таблицы . Присутствие и значение параметров после C зависит от параметров конфигурации таблицы.

Определите, является ли запрос виртуальной таблицы DISTINCT

int sqlite3_vtab_distinct(sqlite3_index_info*);

API может использоваться только из метода xBestIndex вритуальной таблицы. Результат запроса этого интерфейса за пределами xBestIndex() не определен и вероятно вреден.

sqlite3_vtab_distinct() возвращает целое число между 0 и 3. Целое число, возвращенное sqlite3_vtab_distinct(), дает дополнительную информацию виртуальную таблицы о том, как планировщик запроса хочет, чтобы вывод был упорядочен. Пока виртуальная таблица может ответить требованиям порядка планировщика запроса, он может установить флаг "orderByConsumed".

0. Если sqlite3_vtab_distinct() вернет 0, это означает, что планировщику запроса нужна виртуальная таблица, чтобы возвратить все строки в порядке сортировки, определенном полями "nOrderBy" и "aOrderBy" объекта sqlite3_index_info. Это ожидание по умолчанию. Если виртуальная таблица производит все строки в сортированном порядке, то для метода xBestIndex всегда безопасно установить флаг "orderByConsumed", независимо от возвращаемого значения sqlite3_vtab_distinct().

1. Если sqlite3_vtab_distinct() вернет 1, это означает, что планировщику запроса не нужны строки, которые будут возвращены в сортированном порядке, пока все строки с теми же самыми значениями во всех колонках, определенных полем "aOrderBy", смежны. Этот режим используется, когда планировщик запроса делает GROUP BY.

2. Если sqlite3_vtab_distinct() вернет 2, это означает, что планировщику запроса не нужны строки, возвращенные ни в каком конкретном порядке, пока строки с теми же самыми значениями во всех колонках "aOrderBy" смежны. Кроме того, только единственная строка для каждой конкретной комбинации значений в колонках, определенных полем "aOrderBy", должна быть возвращена. Для двух или больше строк с теми же самыми значениями во всех столбцах "aOrderBy" всегда нормально быть возвращенным, пока все такие строки смежны. Виртуальная таблица, если это выбирает, может опустить дополнительные строки, у которых есть то же самое значение для всех колонок, определенных "aOrderBy". Однако, исключение дополнительных строк опционально. Этот режим используется для запроса DISTINCT.

3. Если sqlite3_vtab_distinct() вернет 3, это означает, что планировщику запроса нужны только отличные строки, но этому действительно нужны строки, которые будут сортированы. Виртуальное внедрение таблицы свободно опустить строки, которые идентичны во всех колонках aOrderBy, если оно хочет, но не требуется опускать любые строки. Этот режим используется для запросов, у которых есть пункты DISTINCT и ORDER BY.

В целях сравнить виртуальные выходные значения таблицы, чтобы видеть, являются ли значения тем же самым значением для целей сортировки, два значения NULL считаются тем же самым. Другими словами, оператор сравнения "IS" (или "IS NOT DISTINCT FROM"), но не "==".

Если виртуальное внедрение таблицы не может ответить требованиям, определенным выше, то оно не должно устанавливать флаг "orderByConsumed" в объекте sqlite3_index_info или это может закончиться неправильным ответом.

Виртуальное внедрение таблицы всегда может вернуть строки в любом порядке, который оно хочет, пока флаг "orderByConsumed" не установлен. Когда флаг "orderByConsumed" будет сброшен, планировщик запроса добавит дополнительный байт-код, чтобы гарантировать, что конечные результаты, возвращенные SQL-запросом, упорядочены правильно. Использование флага "orderByConsumed" и интерфейса sqlite3_vtab_distinct() является просто оптимизацией. Тщательное использование sqlite3_vtab_distinct() и флага "orderByConsumed" могло бы помочь запросам для виртуального таблицы работать быстрее. Установка флага "orderByConsumed", когда это не действительно, с другой стороны, могло бы заставить SQLite возвращать неправильные результаты.

Определите и обращайтесь с ограничениями IN в xBestIndex

int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);

Этот интерфейс может использоваться только в методе xBestIndex() виртуальной таблицы. Результат вызова этого интерфейса от любого другого контекста не определен и вероятно вреден.

Ограничение на виртуальную таблицу формы "column IN (...)" сообщено методу xBestIndex как ограничение SQLITE_INDEX_CONSTRAINT_EQ. Если xBestIndex хочет использовать это ограничение, он должен установить соответствующий aConstraintUsage[].argvIndex в положительный integer. Затем под обычным режимом обработки операторов IN SQLite создает байт-код, который вызывает метод xFilter() однажды для каждого значения на правой стороне оператора IN. Таким образом виртуальная таблица видит только единственное значение с правой стороны оператора IN за один раз.

В некоторых случаях, однако, было бы выгодно для виртуальной таблицы видеть все значения справа от оператора IN. sqlite3_vtab_in() облегчает это двумя способами:

1. Запрос sqlite3_vtab_in(P,N,-1) вернет true (не 0) если и только если ограничение P->aConstraint[N] это оператор IN, который может быть обработан за раз. Другими словами, sqlite3_vtab_in() с -1 в третьем аргументе это механизм, которым виртуальная таблица может спросить SQLite, если возможна обработка всего оператора IN за раз.

2. Запрос sqlite3_vtab_in(P,N,F) с F==1 или F==0 указывает SQLite, что виртуальная таблица делает или не хочет обрабатывать оператор IN за раз, соответственно. Таким образом, когда третий параметр (F) неотрицательный, этот интерфейс это механизм, которым виртуальная таблица говорит SQLite, как это хочет обработать оператор IN.

sqlite3_vtab_in(P,N,F) может быть вызван многократно в том же самом вызове метода xBestIndex. Для любой данной пары P,N возвращаемое значение sqlite3_vtab_in(P,N,F) всегда будет тем же самым в рамках того же самого вызова xBestIndex. Если интерфейс возвращает true (не 0), это означает, что ограничение это оператор IN, который может быть обработан за раз. Если ограничение не оператор IN или он не может быть обработан за раз, то интерфейс вернет false.

Одновременная обработка оператора IN отобрана, если обоим из следующих условий отвечают:

1. P->aConstraintUsage[N].argvIndex установлено в положительный integer. Это как виртуальная таблица говорит SQLite, что это хочет использовать N-е ограничение.

2. У последнего вызова sqlite3_vtab_in(P,N,F), для которого F был неотрицательным, был F>=1.

Если хоть одно или оба из условий выше ложные, то SQLite использует традиционную стратегию пошаговой обработки ограничения IN. Если оба условия будут верны, то argvIndex-й параметр метода xFilter будет sqlite3_value, который, кажется, NULL, но который может быть передан sqlite3_vtab_in_first() и sqlite3_vtab_in_next(), чтобы найти все значения на правой стороне ограничения IN.

Определите, обращается ли столбец виртуальной таблицы к UPDATE

int sqlite3_vtab_nochange(sqlite3_context*);

Если sqlite3_vtab_nochange(X) вызван в методе xColumn виртуальной таблицы, то это могло бы возвратить true, если колонка получается как часть операции UPDATE, во время которой не изменится значение столбца. Виртуальное внедрение таблицы может использовать этот намек в качестве разрешения заменить возвращаемым значением, которое менее дорого, чтобы вычислить и что соответствующий метод xUpdate понимает как значение "без изменений".

Если метод xColumn вызывает sqlite3_vtab_nochange() и находит, что колонка не изменяется запросом UPDATE, то метод xColumn может произвольно возвратить, не устанавливая результат, не вызывая ни один из интерфейсов sqlite3_result_xxxxx() interfaces. В этом случае sqlite3_value_nochange(X) вернет true для той же самой колонки в методе xUpdate.

sqlite3_vtab_nochange() является оптимизацией. Виртуальные внедрения таблицы должны продолжить давать правильный ответ, даже если sqlite3_vtab_nochange() должен был всегда возвращать false. В текущем внедрении sqlite3_vtab_nochange() интерфейс всегда вернет false для расширенного UPDATE FROM.

Определите виртуальную политику конфликта таблицы

int sqlite3_vtab_on_conflict(sqlite3 *);

Эта функция может быть вызвана только из метода xUpdate виртуальной таблицы для операции UPDATE или INSERT. Возвращенное значение является одним из SQLITE_ROLLBACK, SQLITE_IGNORE, SQLITE_FAIL, SQLITE_ABORT или SQLITE_REPLACE, согласно режиму ON CONFLICT SQL-оператора, который вызвал запрос к методу xUpdate виртуальной таблицы.

Ограничение значений в xBestIndex()

int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);

API может использоваться только из метода xBestIndex виртуальной таблицы. Результат запроса этого интерфейса за пределами метода xBestIndex не определен и вероятно вреден.

Когда sqlite3_vtab_rhs_value(P,J,V) вызван из метода xBestIndex виртуальной таблицы, P должен копией указателя на объект sqlite3_index_info, переданного xBestIndex, а J это индекс на основе 0 в P->aConstraint[], тогда это пытается установить *V в значение правого операнда того ограничения, если правый операнд известен. Если правый операнд неизвестен, то *V установлен в NULL. sqlite3_vtab_rhs_value(P,J,V) вернет SQLITE_OK если и только если *V установлен в значение. sqlite3_vtab_rhs_value(P,J,V) вернет SQLITE_NOTFOUND, если правая сторона J-го ограничения недоступна. sqlite3_vtab_rhs_value() может возвратить код результата кроме SQLITE_OK или SQLITE_NOTFOUND, если что-то идет не так, как надо.

sqlite3_vtab_rhs_value() обычно успешен только, если правый операнд ограничения это литеральное значение в оригинальном SQL-операторе. Если правый операнд будет выражением или ссылкой на некоторую другую колонку или a параметром хоста, sqlite3_vtab_rhs_value(), вероятно, возвратит SQLITE_NOTFOUND.

У некоторых ограничений, таких как SQLITE_INDEX_CONSTRAINT_ISNULL и SQLITE_INDEX_CONSTRAINT_ISNOTNULL, нет правого операнда. Для таких ограничений sqlite3_vtab_rhs_value() всегда вернет SQLITE_NOTFOUND.

Объект sqlite3_value, возвращенный в *V, является защищенным sqlite3_value и остается действительным на время вызова метода xBestIndex. Когда xBestIndex возвращается, объект sqlite3_value, возвращенный sqlite3_vtab_rhs_value(), автоматически освобожден.

"_rhs_" в имени это сокращение для "Right-Hand Side".

Формируйте автоконтрольную точку

int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

sqlite3_wal_autocheckpoint(D,N) это оболочка для sqlite3_wal_hook(), который вызывает любую базу данных по соединению с базой данных D для автоматической контрольной точки после совершения транзакции, если есть N или больше структур в файле журнала с упреждающей записью. Передача ноля или отрицательной величины как nFrame отключают автоматические контрольные точки полностью.

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

wal_autocheckpoint pragma может использоваться, чтобы вызвать этот интерфейс из SQL.

Контрольными точками, начатыми этим механизмом, является PASSIVE.

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

Контрольная точка базы данных

int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);

sqlite3_wal_checkpoint(D,X) эквивалент sqlite3_wal_checkpoint_v2(D,X, SQLITE_CHECKPOINT_PASSIVE,0,0).

Вкратце, sqlite3_wal_checkpoint(D,X) заставляет содержание журнала с упреждающей записью для БД X на соединении с базой данных D быть переданным в файл базы данных и перезагрузить журнал с упреждающей записью. См. checkpointing для подробностей.

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

Контрольная точка базы данных

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Database handle */
  const char *zDb,                /* Name of attached database (or NULL) */
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
  int *pnLog,                     /* OUT: Size of WAL log in frames */
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
);

sqlite3_wal_checkpoint_v2(D,X,M,L,C) управляет операцией по контрольной точке на базе данных X из соединения с базой данных D в методе M. Информация о статусе написана в ответ в виде целых чисел, на которые указывают L и C. Параметр M должен быть действительным режимом контрольной точки:

SQLITE_CHECKPOINT_PASSIVE

Контрольная точка как можно больше структур, не ожидая окончания никаких чтений и записей базы данных, затем синхронизируйте файл базы данных, если все структуры в журнале были сохранены. busy-handler callback никогда не вызывается в режиме SQLITE_CHECKPOINT_PASSIVE. С другой стороны, пассивный режим мог бы оставить контрольную точку незаконченной, если есть параллельные чтения или записи.

SQLITE_CHECKPOINT_FULL

Этот режим блокирует (это вызывает busy-handler callback), пока все записи в БД не будут сделаны, а все чтения делаются от более нового образа БД. Это тогда сохраняет все структуры в файле журнала и делают синхронизацию файла базы данных. Этот режим блокирует новые записи в БД в то время, как он работает, но новые чтения разрешают продолжить.

SQLITE_CHECKPOINT_RESTART

Этот режим работает аналогично SQLITE_CHECKPOINT_FULL с дополнением, которое после сохранения файла журнала это блокирует (вызывая busy-handler callback), пока все читатели читают только от файла базы данных. Это гарантирует, что следующая запись перезапустит файл журнала с начала. Как SQLITE_CHECKPOINT_FULL, этот режим блокирует новые попытки записи базы данных, в то время как это работает, но не препятствует читателям.

SQLITE_CHECKPOINT_TRUNCATE

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

Если pnLog не NULL, *pnLog установлен в общее количество структур в файле журнала или в -1, если контрольная точка не могла бы работать из-за ошибки или потому что база данных не находится в режиме WAL. Если pnCkpt не NULL, *pnCkpt установлен в общее количество структур в файле журнала (включая любые, которые уже были сохранены прежде чем функция была вызвана) или в -1, если контрольная точка не могла бы работать из-за ошибки или потому что база данных не находится в режиме WAL. Обратите внимание на то, что после успешного завершения SQLITE_CHECKPOINT_TRUNCATE, файл журнала будет усечен к нулю байт, таким образом, *pnLog и *pnCkpt установлены в 0.

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

Режимы SQLITE_CHECKPOINT_FULL, RESTART и TRUNCATE также получают исключительную блокировку записи файла базы данных. Если блокировка записи не может быть немедленно получена, а занятый обработчик формируется, он вызван, и блокировка записи повторена до возврата обработчиком 0 или до успешного полученения блокировки. Занятый обработчик также вызван, ожидая чтения базы данных, как описано выше. Если занятый обработчик возвращает 0, прежде чем блокировка записи будет получена или ожидая чтения базы данных, операция контрольной точки выполняется от того пункта таким же образом как SQLITE_CHECKPOINT_PASSIVE, сохраняя как можно больше структур, не блокируя ничего дальше. SQLITE_BUSY возвращен в этом случае.

Если zDb = NULL или указывает на строку нулевой длины, то указанная операция предпринята на всех базах данных WAL присоединенных к соединению db. В этом случае значения, написанные, чтобы произвести параметры *pnLog и *pnCkpt, не определены. Если с ошибкой SQLITE_BUSY сталкиваются, обрабатывая одну или больше приложенных баз данных WAL, операция все еще предпринята на любых остающихся приложенных базах данных, а SQLITE_BUSY возвращен в конце. Если какая-либо другая ошибка происходит, обрабатывая приложенную базу данных, обработка остановлена, а код ошибки немедленно возвращен. Если ни с какой ошибкой (SQLITE_BUSY или иной) не сталкиваются, обрабатывая приложенные базы данных, SQLITE_OK возвращен.

Если zDb является названием приложенной базы данных, которая не находится в режиме WAL, SQLITE_OK возвращен, *pnLog и *pnCkpt установлены в -1. Если zDb не NULL (или строка нулевой длины) и не является названием никакой приложенной базы данных, SQLITE_ERROR возвращен.

Если это не возвращает SQLITE_MISUSE, sqlite3_wal_checkpoint_v2() устанавливает информацию об ошибке, которая запрашивается sqlite3_errcode() и sqlite3_errmsg().

PRAGMA wal_checkpoint может использоваться, чтобы вызвать этот интерфейс от SQL.

Журнал с упреждающей записью передачи

void *sqlite3_wal_hook(sqlite3*, int(*)(void *,sqlite3*,
                       const char*,int), void*);

sqlite3_wal_hook() используется, чтобы зарегистрировать отзыв, который вызван каждый раз, когда данные пишутся в базу данных в wal-режиме.

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

Первый параметр, переданный функции обратного вызова, когда это вызвано, является копией третьего параметра, переданного sqlite3_wal_hook(), регистрируя отзыв. Второй является копией обработчика базы данных. Третий параметр это название базы данных, которая была написана, "main" или название базы данных из ATTACH. Четвертый параметр это число страниц в настоящее время в файле журнала с упреждающей записью, включая те, которые были просто переданы.

Функция обратного вызова должна обычно возвращать SQLITE_OK. Если код ошибки будет возвращен, та ошибка размножится назад через кодовую базу SQLite, чтобы вызвать запрос, который побудил отзыв сообщать об ошибке, хотя передача все еще произойдет. Если отзыв возвращает SQLITE_ROW или SQLITE_DONE, или если это возвращает значение, которое не соответствует никакому действительному коду ошибки SQLite, результаты не определены.

У одной базы данных может быть самое большее единственный отзыв журнала с упреждающей записью, зарегистрированный когда-то. Вызов sqlite3_wal_hook() заменяет любой ранее зарегистрированный отзыв журнала с упреждающей записью. Возвращаемое значение это копия третьего параметра от предыдущего вызова, если есть, или 0. Обратите внимание на то, что sqlite3_wal_autocheckpoint() и wal_autocheckpoint pragma вызывают sqlite3_wal_hook() и перепишут любой предшествующий sqlite3_wal_hook().

Коды результатов

#define SQLITE_OK           0   /* Successful result */
/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* Generic error */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Internal use only */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Not used */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
#define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
/* end-of-error-codes */

Много функций SQLite возвращают код результата в виде целого числа из набора, показанного здесь, чтобы указать на успешность или неуспешность.

Новые коды ошибок могут быть добавлены в будущих версиях SQLite.

Расширенные коды результата

#define SQLITE_ERROR_MISSING_COLLSEQ   (SQLITE_ERROR | (1<<8))
#define SQLITE_ERROR_RETRY             (SQLITE_ERROR | (2<<8))
#define SQLITE_ERROR_SNAPSHOT          (SQLITE_ERROR | (3<<8))
#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
#define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
#define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
#define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
#define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
#define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))
#define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))
#define SQLITE_IOERR_BEGIN_ATOMIC      (SQLITE_IOERR | (29<<8))
#define SQLITE_IOERR_COMMIT_ATOMIC     (SQLITE_IOERR | (30<<8))
#define SQLITE_IOERR_ROLLBACK_ATOMIC   (SQLITE_IOERR | (31<<8))
#define SQLITE_IOERR_DATA              (SQLITE_IOERR | (32<<8))
#define SQLITE_IOERR_CORRUPTFS         (SQLITE_IOERR | (33<<8))
#define SQLITE_IOERR_IN_PAGE           (SQLITE_IOERR | (34<<8))
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
#define SQLITE_LOCKED_VTAB             (SQLITE_LOCKED |  (2<<8))
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
#define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
#define SQLITE_BUSY_TIMEOUT            (SQLITE_BUSY   |  (3<<8))
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
#define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
#define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
#define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
#define SQLITE_CANTOPEN_SYMLINK        (SQLITE_CANTOPEN | (6<<8))
#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
#define SQLITE_CORRUPT_SEQUENCE        (SQLITE_CORRUPT | (2<<8))
#define SQLITE_CORRUPT_INDEX           (SQLITE_CORRUPT | (3<<8))
#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
#define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
#define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
#define SQLITE_READONLY_CANTINIT       (SQLITE_READONLY | (5<<8))
#define SQLITE_READONLY_DIRECTORY      (SQLITE_READONLY | (6<<8))
#define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
#define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
#define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
#define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
#define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
#define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
#define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
#define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
#define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
#define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
#define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
#define SQLITE_CONSTRAINT_PINNED       (SQLITE_CONSTRAINT |(11<<8))
#define SQLITE_CONSTRAINT_DATATYPE     (SQLITE_CONSTRAINT |(12<<8))
#define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
#define SQLITE_NOTICE_RBU              (SQLITE_NOTICE | (3<<8))
#define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
#define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))
#define SQLITE_OK_LOAD_PERMANENTLY     (SQLITE_OK | (1<<8))
#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */

В конфигурации по умолчанию SQLite API возвращает один из 30 integer кодов результата. Однако опыт показал, что многие из этих кодов результата слишком общие. Они не предоставляют столько информации о проблемах, сколько программистам надо. Чтобы решить проблему, более новые версии SQLite (версия 3.3.8 2006-10-09 и позже) включают поддержку дополнительных кодов результата, которые предоставляют более подробную информацию об ошибках. Эти расширенные коды результата позволены или отключены на основе связи для каждой базы данных, используя sqlite3_extended_result_codes() API. Или расширенный код для новой ошибки может быть получен, используя sqlite3_extended_errcode().

Флаги метода xAccess VFS

#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
#define SQLITE_ACCESS_READ      2   /* Unused */

Эти константы integer могут использоваться в качестве третьего параметра метода xAccess объекта sqlite3_vfs. Они определяют, какие разрешения xAccess метод ищет. С SQLITE_ACCESS_EXISTS метод xAccess просто проверяет, существует ли файл. С SQLITE_ACCESS_READWRITE метод xAccess проверяет, что названный каталог читаемый и перезаписываемый (другими словами, если файлы могут быть добавлены, удалены и переименованы в рамках каталога). SQLITE_ACCESS_READWRITE в настоящее время используется только прагмой temp_store_directory, хотя это могло измениться в будущем выпуске SQLite. С SQLITE_ACCESS_READ xAccess проверяет, читаемый ли файл. Константа SQLITE_ACCESS_READ в настоящее время не использована, хотя она могла бы использоваться в будущем выпуске SQLite.

Коды действия авторизатора

/******************************************* 3rd ************ 4th ***********/
#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
#define SQLITE_DELETE                9   /* Table Name      NULL            */
#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
#define SQLITE_INSERT               18   /* Table Name      NULL            */
#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
#define SQLITE_READ                 20   /* Table Name      Column Name     */
#define SQLITE_SELECT               21   /* NULL            NULL            */
#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
#define SQLITE_ATTACH               24   /* Filename        NULL            */
#define SQLITE_DETACH               25   /* Database Name   NULL            */
#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
#define SQLITE_REINDEX              27   /* Index Name      NULL            */
#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
#define SQLITE_COPY                  0   /* No longer used */
#define SQLITE_RECURSIVE            33   /* NULL            NULL            */

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

Эти кодовые обозначения действия имеют значение, какая операция должна быть разрешена. 3-й и 4-й параметры функции обратного вызова разрешения будут параметрами или NULL в зависимости от, который из этих кодов используется в качестве второго параметра. 5-й параметр авторизатора это название базы данных ("main", "temp" и т. д.), если возможно. 6-й параметр авторизатора это название самого внутреннего триггера или обзора, который ответственен за попытку доступа или NULL, если это попытка доступа непосредственно от кода SQL верхнего уровня.

Кодирование текста

#define SQLITE_UTF8           1    /* IMP: R-37514-35566 */
#define SQLITE_UTF16LE        2    /* IMP: R-03371-37637 */
#define SQLITE_UTF16BE        3    /* IMP: R-51971-34154 */
#define SQLITE_UTF16          4    /* Use native byte order */
#define SQLITE_ANY            5    /* Deprecated */
#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */

Эти постоянные определяют коды целого числа, которые представляют различное текстовое кодирование, поддержанное SQLite.

Основополагающие типы данных

#define SQLITE_INTEGER  1
#define SQLITE_FLOAT    2
#define SQLITE_BLOB     4
#define SQLITE_NULL     5
#ifdef SQLITE_TEXT
# undef SQLITE_TEXT
#else
# define SQLITE_TEXT     3
#endif
#define SQLITE3_TEXT     3

У каждого значения в SQLite есть один из пяти основополагающих типов данных:

• 64-bit signed integer
• 64-bit IEEE floating point number
• string
• BLOB
• NULL

Эти константы это коды для каждого из тех типов.

Обратите внимание на то, что константа SQLITE_TEXT также использовалась в версии SQLite version 2 для совершенно другого значения. Программное обеспечение, которое связывается компонуется для версий 2 и 3 сразу, должно использовать SQLITE3_TEXT, но не SQLITE_TEXT.

Значения режима контрольной точки

#define SQLITE_CHECKPOINT_PASSIVE  0  /* Do as much as possible w/o blocking */
#define SQLITE_CHECKPOINT_FULL     1  /* Wait for writers, then checkpoint */
#define SQLITE_CHECKPOINT_RESTART  2  /* Like FULL but wait for readers */
#define SQLITE_CHECKPOINT_TRUNCATE 3  /* Like RESTART but also truncate WAL */

Эти константы определяют все действительные значения для "режима контрольной точки", переданного как третий параметр sqlite3_wal_checkpoint_v2().

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

#define SQLITE_CONFIG_SINGLETHREAD         1  /* nil */
#define SQLITE_CONFIG_MULTITHREAD          2  /* nil */
#define SQLITE_CONFIG_SERIALIZED           3  /* nil */
#define SQLITE_CONFIG_MALLOC               4  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_GETMALLOC            5  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_SCRATCH              6  /* No longer used */
#define SQLITE_CONFIG_PAGECACHE            7  /* void*, int sz, int N */
#define SQLITE_CONFIG_HEAP                 8  /* void*, int nByte, int min */
#define SQLITE_CONFIG_MEMSTATUS            9  /* boolean */
#define SQLITE_CONFIG_MUTEX               10  /* sqlite3_mutex_methods* */
#define SQLITE_CONFIG_GETMUTEX            11  /* sqlite3_mutex_methods* */
/* previously SQLITE_CONFIG_CHUNKALLOC    12 which is now unused. */
#define SQLITE_CONFIG_LOOKASIDE           13  /* int int */
#define SQLITE_CONFIG_PCACHE              14  /* no-op */
#define SQLITE_CONFIG_GETPCACHE           15  /* no-op */
#define SQLITE_CONFIG_LOG                 16  /* xFunc, void* */
#define SQLITE_CONFIG_URI                 17  /* int */
#define SQLITE_CONFIG_PCACHE2             18  /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_GETPCACHE2          19  /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
#define SQLITE_CONFIG_SQLLOG              21  /* xSqllog, void* */
#define SQLITE_CONFIG_MMAP_SIZE           22  /* sqlite3_int64, sqlite3_int64 */
#define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
#define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */
#define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */
#define SQLITE_CONFIG_STMTJRNL_SPILL      26  /* int nByte */
#define SQLITE_CONFIG_SMALL_MALLOC        27  /* boolean */
#define SQLITE_CONFIG_SORTERREF_SIZE      28  /* int nByte */
#define SQLITE_CONFIG_MEMDB_MAXSIZE       29  /* sqlite3_int64 */

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

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

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

• SQLITE_CONFIG_LOG
• SQLITE_CONFIG_PCACHE_HDRSZ

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

SQLITE_CONFIG_SINGLETHREAD

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

SQLITE_CONFIG_MULTITHREAD

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

SQLITE_CONFIG_SERIALIZED

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

SQLITE_CONFIG_MALLOC

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

SQLITE_CONFIG_GETMALLOC

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

SQLITE_CONFIG_SMALL_MALLOC

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

SQLITE_CONFIG_MEMSTATUS

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

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

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

SQLITE_CONFIG_SCRATCH

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

SQLITE_CONFIG_PAGECACHE

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

SQLITE_CONFIG_HEAP

SQLITE_CONFIG_HEAP определяет буфер статической памяти, который SQLite будет использовать для всех его потребностей динамического выделения памяти вне предусмотренных SQLITE_CONFIG_PAGECACHE. SQLITE_CONFIG_HEAP доступен только если SQLite собран с SQLITE_ENABLE_MEMSYS3 или SQLITE_ENABLE_MEMSYS5 и возвращает SQLITE_ERROR, если вызвано иначе. Есть три аргумента SQLITE_CONFIG_HEAP: выровненный на 8 байтов указатель на память, число байтов в буфере памяти и минимальный размер распределения. Если первым указателем (указатель памяти) является NULL, то SQLite возвращается к использованию своего распределителя памяти по умолчанию (системная реализация malloc()), отменяя любой предшествующий вызов SQLITE_CONFIG_MALLOC. Если указатель памяти не NULL, тогда альтернативный распределитель памяти используется, чтобы обращаться со всеми потребностями выделения памяти SQLite. Первый указатель (указатель памяти) должен быть выровнен на 8 байт или последующее поведение SQLite будет не определено. Минимальный размер распределения ограничен в Минимальный размер распределения ограничен 2**12. Обычное значение для минимального размера распределения от 2**5 до 2**8.

SQLITE_CONFIG_MUTEX

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

SQLITE_CONFIG_GETMUTEX

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

SQLITE_CONFIG_LOOKASIDE

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

SQLITE_CONFIG_PCACHE2

SQLITE_CONFIG_PCACHE2 берет отдельный аргумент, который является указателем на объект sqlite3_pcache_methods2. Этот объект определяет интерфейс к внедрению кэша страницы. SQLite делает копию объекта sqlite3_pcache_methods2.

SQLITE_CONFIG_GETPCACHE2

SQLITE_CONFIG_GETPCACHE2 берет отдельный аргумент, который является указателем на объект sqlite3_pcache_methods2. SQLite делает копию текущего внедрения кэша страницы в этот объект.

SQLITE_CONFIG_LOG

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

SQLITE_CONFIG_URI

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

SQLITE_CONFIG_COVERING_INDEX_SCAN

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

SQLITE_CONFIG_PCACHE и SQLITE_CONFIG_GETPCACHE

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

SQLITE_CONFIG_SQLLOG

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

SQLITE_CONFIG_MMAP_SIZE

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

SQLITE_CONFIG_WIN32_HEAPSIZE

SQLITE_CONFIG_WIN32_HEAPSIZE доступен только если SQLite собран для Windows с определенным макросом препроцессора SQLITE_WIN32_MALLOC. SQLITE_CONFIG_WIN32_HEAPSIZE берет 32-битное значение целого без знака, которое определяет максимальный размер созданной кучи.

SQLITE_CONFIG_PCACHE_HDRSZ

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

SQLITE_CONFIG_PMASZ

SQLITE_CONFIG_PMASZ берет единственный параметр, который является целым без знака и устанавливает "Minimum PMA Size" для многопоточного сортировщика к этому целому числу. Минимум по умолчанию PMA Size устанавливается выбором времени компиляции SQLITE_SORTER_PMASZ. Новые потоки начаты, чтобы помочь с операциями по сортировке, когда многопоточная сортировка позволена (использование команды PRAGMA threads) и сумма содержания, которое будет сортировано, превышает число размеров страницы на минимум из PRAGMA cache_size и этого значения.

SQLITE_CONFIG_STMTJRNL_SPILL

SQLITE_CONFIG_STMTJRNL_SPILL берет единственный параметр, который становится порогом сброса на диск журнала запросов. Журналы запросов проводятся в памяти, пока их размер (в байтах) не превышает этот порог, тогда они записаны на диск. Или если порог -1, журналы всегда проводятся исключительно в памяти. Так как много журналов запросов никогда не становятся большими, указание порога в 64KiB может значительно уменьшить сумму I/O, требуемого, чтобы поддерживать обратную перемотку запросов. Значением по умолчанию для этого управляет выбор времени компиляции SQLITE_STMTJRNL_SPILL.

SQLITE_CONFIG_SORTERREF_SIZE

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

SQLITE_CONFIG_MEMDB_MAXSIZE

SQLITE_CONFIG_MEMDB_MAXSIZE принимает единственный параметр sqlite3_int64, который является размером максимума по умолчанию для базы данных в памяти, созданной, используя sqlite3_deserialize(). Этот размер максимума по умолчанию может быть адаптирован для отдельных баз данных, используя SQLITE_FCNTL_SIZE_LIMIT file-control. Если этот параметр конфигурации никогда не используется, то максимум по умолчанию определяется выбором времени компиляции SQLITE_MEMDB_DEFAULT_MAXSIZE. Если тот выбор времени компиляции не установлен, то максимум по умолчанию 1073741824.

Параметры конфигурации соединения с базой данных

#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

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

SQLITE_DBCONFIG_ENABLE_FKEY

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

SQLITE_DBCONFIG_ENABLE_TRIGGER

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

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

SQLITE_DBCONFIG_ENABLE_VIEW

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

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

SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

Этот выбор используется, чтобы позволить или отключить функцию fts3_tokenizer(), которая является частью полнотекстового расширения поисковой системы FTS3. Должно быть два дополнительных аргумента. Первый аргумент это которое является 0, чтобы отключить, положительное, чтобы включить, или отрицательное, чтобы оставить урегулирование без изменений. Второй параметр это указатель на целое число, в которое написан 0 или 1, чтобы указать, отключено ли. Второй параметр может быть 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, то никакие изменения не внесены. Второй параметр это указатель на целое число, в которое написан 0 или 1, чтобы указать, отключен ли интерфейс sqlite3_load_extension(). Второй параметр может быть NULL, в этом случае новое урегулирование не отчитывается.

SQLITE_DBCONFIG_MAINDBNAME

Этот выбор используется, чтобы изменить название "main" схемы базы данных. Единственный аргумент это указатель на постоянную последовательность UTF8, которая станет новым названием схемы вместо "main". SQLite не делает копию новой последовательности названия схемы, таким образом, применение должно гарантировать, что аргумент, переданный в этот выбор DBCONFIG неизменен, пока соединение с базой данных не закрывается.

SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

Обычно, когда база данных в wal-режиме закрыта или отделена от обработчика базы данных, SQLite проверяет, будет ли это означать, что теперь нет никаких связей вообще с базой данных. Если так, это выполняет операцию по контрольной точке прежде, чем закрыть связь. Этот выбор может использоваться, чтобы отвергнуть это поведение. Первый параметр, переданный к этой операции, является целым числом: положительным, чтобы отключить контрольные точки на завершении, ноль (умолчание), чтобы позволить их, и отрицательное, чтобы оставить урегулирование без изменений. Второй параметр это указатель на целое число, в которое написан 0 или 1, чтобы указать, были ли контрольные точки отключены: 0, если они включены, 1, если они выключены.

SQLITE_DBCONFIG_ENABLE_QPSG

SQLITE_DBCONFIG_ENABLE_QPSG активирует или дезактивирует query planner stability guarantee (QPSG). Когда QPSG активен, единственное выполнение SQL-запроса будет всегда использовать тот же самый алгоритм независимо от значений связанных параметров. QPSG отключает некоторые оптимизации запросов, которые смотрят на значения связанных параметров, которые могут сделать некоторые запросы медленнее. Но QPSG имеет преимущество более предсказуемого поведения. С активным QPSG SQLite будет всегда использовать тот же самый план запросов, какой использовался во время тестирования в лаборатории. Первый аргумент этому урегулированию это целое число, которое является 0, чтобы отключить QPSG, положительным, чтобы позволить QPSG, или отрицательным, чтобы оставить урегулирование без изменений. Второй параметр это указатель на целое число, в которое написан 0 или 1, чтобы указать, отключен ли QPSG или позволен после этого вызова.

SQLITE_DBCONFIG_TRIGGER_EQP

По умолчанию вывод EXPLAIN QUERY PLAN не включает вывод ни для каких операций, выполненных триггерами. Этот выбор используется, чтобы установить или очистить (умолчание) флаг, который управляет этим поведением. Первый параметр, переданный к этой операции, является целым числом, положительным, чтобы включить вывод от триггеров, 0 для отключения или отрицательным, чтобы оставить урегулирование без изменений. Второй параметр это указатель на целое число, в которое написан 0 или 1, чтобы указать, был ли вывод от триггеров отключен: 0, если выключен, 1, если включен.

SQLITE_DBCONFIG_RESET_DATABASE

Установите флаг SQLITE_DBCONFIG_RESET_DATABASE и затем выполните VACUUM, чтобы перезагрузить базу данных назад к пустой базе данных без схемы и содержания. Следующий процесс работает даже на ужасно испорченном файле базы данных:

1. Если соединение с базой данных недавно открыто, удостоверьтесь, что оно прочитало схему базы данных, вызывая sqlite3_table_column_metadata(), игнорируя любые ошибки. Этот шаг необходим только если применение желает держать базу данных в режиме WAL после сброса, если это было в режиме WAL перед сбросом.
2. sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
3. sqlite3_exec(db, "VACUUM", 0, 0, 0);
4. 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, как это сделано до версии version 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.

Это урегулирование по умолчанию "on" для совместимости с прежними системами, однако всем приложениям рекомендуют выключить его, если это возможно. Этим урегулированием можно также управлять, используя 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).

Обратите внимание на то, что, когда SQLITE_DBCONFIG_LEGACY_FILE_FORMAT = on, команда 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, чтобы позволить, отключить или оставить без изменений выбор scanstatus. Если второй аргумент не NULL, то значение scanstatus после обработки первого аргумента написано в целое число, на которое указывает второй аргумент.

SQLITE_DBCONFIG_REVERSE_SCANORDER

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

Коды возврата авторизатора

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */

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

Обратите внимание на то, что SQLITE_IGNORE также используется в качестве режима разрешения конфликтов возвращенного из sqlite3_vtab_on_conflict().

Флаги для sqlite3_deserialize()

#define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
#define SQLITE_DESERIALIZE_RESIZEABLE  2 /* Resize using sqlite3_realloc64() */
#define SQLITE_DESERIALIZE_READONLY    4 /* Database is read-only */

Это значения для 6-го аргумента (аргумент F) sqlite3_deserialize(D,S,P,N,M,F).

SQLITE_DESERIALIZE_FREEONCLOSE означает, что преобразование в последовательную форму базы данных в аргументе P проведено в памяти, полученной из sqlite3_malloc64() и что SQLite должен принять эту память и автоматически освободить ее, когда закончит использовать. Без этого флага вызывающий ответственен за освобождение любой динамично ассигнованной памяти.

SQLITE_DESERIALIZE_RESIZEABLE означает, что SQLite позволяют вырастить размер базы данных, используя sqlite3_realloc64() . Этот флаг должен использоваться только, если SQLITE_DESERIALIZE_FREEONCLOSE также используется. Без этого флага десериализованная база данных не может увеличиться в размере сверх количества байтов, определенных параметром M.

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

Флаги функции

#define SQLITE_DETERMINISTIC    0x000000800
#define SQLITE_DIRECTONLY       0x000080000
#define SQLITE_SUBTYPE          0x000100000
#define SQLITE_INNOCUOUS        0x000200000

Эти константы могут быть OR вместе с предпочтительным кодированием текста как четвертый аргумент для sqlite3_create_function(), sqlite3_create_function16() или sqlite3_create_function_v2().

SQLITE_DETERMINISTIC

SQLITE_DETERMINISTIC означает, что новая функция всегда дает тот же самый вывод, когда входные параметры те же самые. Функция abs() детерминирована, например, но randomblob() нет. Функции должны быть детерминированы, чтобы использоваться в определенных контекстах, как с оператором Where частичных индексов или в произведенных колонках . SQLite мог бы также оптимизировать детерминированные функции, учтя их из внутренних циклов.

SQLITE_DIRECTONLY

SQLITE_DIRECTONLY означает, что функция может быть вызвана только от SQL верхнего уровня и не может использоваться в VIEW, TRIGGER или в структурах схемы, таких как ограничения CHECK , DEFAULT, индексы выражения, частичные индексы или произведенные колонки.

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

Некоторые люди говорят, что хорошая практика, чтобы установить SQLITE_DIRECTONLY на всех созданных приложением функциях SQL, независимо от того, являются ли они чувствительными для безопасности, поскольку выполнение этого препятствует тому, чтобы те функции использовались в схеме базы данных, и таким образом гарантирует, что база данных может быть просмотрена и изменена, используя универсальные инструменты (такие, как CLI), у которых нет доступа к определенным применением функциям.

SQLITE_INNOCUOUS

SQLITE_INNOCUOUS означает, что функция вряд ли вызовет проблемы даже если неправильно используется. Безвредная функция не должна иметь никаких побочных эффектов и не должна зависеть ни от каких значений кроме ее входных параметров. Функция abs() это пример безвредной функции. Функция SQL load_extension() весьма вредна из-за ее побочных эффектов.

SQLITE_INNOCUOUS аналог SQLITE_DETERMINISTIC, но не является точно тем же самым. Функция random() это пример функции, которая безвредна, но не детерминирована.

Некоторые усиленные настройки безопасности (SQLITE_DBCONFIG_TRUSTED_SCHEMA и PRAGMA trusted_schema=OFF) отключают использование функций SQL в обзорах, триггерах и структурах схемы, таких как ограничения CHECK, DEFAULT, индексы выражения, частичные индексы и произведенные колонки, если функция не помечена SQLITE_INNOCUOUS. Большинство встроенных функций безвредно. Разработчикам рекомендуют избегать использования флага SQLITE_INNOCUOUS для определенных применением функций, если функция не была тщательно ревизована и свободна от потенциально неблагоприятных безопасности побочных эффектов и информационных утечек.

SQLITE_SUBTYPE

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

Режимы разрешения конфликтов

#define SQLITE_ROLLBACK 1
/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
#define SQLITE_FAIL     3
/* #define SQLITE_ABORT 4  // Also an error code */
#define SQLITE_REPLACE  5

Эти константы возвращены sqlite3_vtab_on_conflict(), чтобы сообщить виртуальной таблице, что режим ON CONFLICT включен для оцениваемого SQL-оператора.

Обратите внимание на то, что константа SQLITE_IGNORE также используется в качестве потенциального возвращаемого значения от отзыва sqlite3_set_authorizer() и что также SQLITE_ABORT также код результата.

Стандартные коды операции контроля за файлом

#define SQLITE_FCNTL_LOCKSTATE               1
#define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
#define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
#define SQLITE_FCNTL_LAST_ERRNO              4
#define SQLITE_FCNTL_SIZE_HINT               5
#define SQLITE_FCNTL_CHUNK_SIZE              6
#define SQLITE_FCNTL_FILE_POINTER            7
#define SQLITE_FCNTL_SYNC_OMITTED            8
#define SQLITE_FCNTL_WIN32_AV_RETRY          9
#define SQLITE_FCNTL_PERSIST_WAL            10
#define SQLITE_FCNTL_OVERWRITE              11
#define SQLITE_FCNTL_VFSNAME                12
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
#define SQLITE_FCNTL_PRAGMA                 14
#define SQLITE_FCNTL_BUSYHANDLER            15
#define SQLITE_FCNTL_TEMPFILENAME           16
#define SQLITE_FCNTL_MMAP_SIZE              18
#define SQLITE_FCNTL_TRACE                  19
#define SQLITE_FCNTL_HAS_MOVED              20
#define SQLITE_FCNTL_SYNC                   21
#define SQLITE_FCNTL_COMMIT_PHASETWO        22
#define SQLITE_FCNTL_WIN32_SET_HANDLE       23
#define SQLITE_FCNTL_WAL_BLOCK              24
#define SQLITE_FCNTL_ZIPVFS                 25
#define SQLITE_FCNTL_RBU                    26
#define SQLITE_FCNTL_VFS_POINTER            27
#define SQLITE_FCNTL_JOURNAL_POINTER        28
#define SQLITE_FCNTL_WIN32_GET_HANDLE       29
#define SQLITE_FCNTL_PDB                    30
#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
#define SQLITE_FCNTL_LOCK_TIMEOUT           34
#define SQLITE_FCNTL_DATA_VERSION           35
#define SQLITE_FCNTL_SIZE_LIMIT             36
#define SQLITE_FCNTL_CKPT_DONE              37
#define SQLITE_FCNTL_RESERVE_BYTES          38
#define SQLITE_FCNTL_CKPT_START             39
#define SQLITE_FCNTL_EXTERNAL_READER        40
#define SQLITE_FCNTL_CKSM_FILE              41
#define SQLITE_FCNTL_RESET_CACHE            42

Эти константы целого числа это коды операции для метода xFileControl объекта sqlite3_io_methods и для sqlite3_file_control().

• SQLITE_FCNTL_LOCKSTATE используется для отладки. Этот код операции заставляет метод xFileControl писать текущее состояние блокировки (одно из SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING или SQLITE_LOCK_EXCLUSIVE) в целое число, на которое указывает аргумент pArg. Это доступно только, если SQLite собран с SQLITE_DEBUG.

• SQLITE_FCNTL_SIZE_HINT используется SQLite, чтобы дать слою VFS намек, как большой файл базы данных вырастет во время текущей транзакции. Этот намек, как гарантируют, не будет точен, но это часто близко. Основной VFS мог бы предварительно ассигновать файловое пространство базы данных на основе этого намека, чтобы помочь записи файла базы данных, которым управляют быстрее.

• SQLITE_FCNTL_SIZE_LIMIT используется VFS в памяти, который осуществляет sqlite3_deserialize(), чтобы установить верхнюю границу размера базы данных в памяти. Аргумент это указатель на sqlite3_int64. Если целое число отрицательно, то это заполнено текущим пределом. Иначе предел устанавливается к большему из указанного значения целого числа и текущего размера базы данных.

• SQLITE_FCNTL_CHUNK_SIZE используется, чтобы запросить, чтобы VFS расширил и усек файл базы данных в кусках размера, определенного пользователем. Четвертый аргумент sqlite3_file_control() должен указать на целое число (тип int), содержащий новый размер куска, чтобы использовать для назначенной базы данных. Распределение файлового пространства базы данных в больших кусках (например, 1MB за раз) может уменьшить фрагментацию файловой системы и улучшить работу относительно некоторых систем.

• SQLITE_FCNTL_FILE_POINTER используется, чтобы получить указатель на объект sqlite3_file, связанный с конкретным соединением с базой данных. См. также SQLITE_FCNTL_JOURNAL_POINTER.

• SQLITE_FCNTL_JOURNAL_POINTER используется, чтобы получить указатель на объект sqlite3_file, связанный с файлом журнала (журнал обратной перемотки или журнал с упреждающей записью) для конкретного соединения с базой данных. См. также SQLITE_FCNTL_FILE_POINTER.

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

• SQLITE_FCNTL_SYNC произведен внутренне SQLite и немедленно послан в VFS, прежде чем метод xSync будет вызван на дескрипторе файла базы данных. Или, если метод xSync не вызван, потому что пользователь формировал SQLite с PRAGMA synchronous=OFF это вызвано вместо метода xSync. В большинстве случаев аргументом указателя, переданным с этим контролем файла, является NULL. Однако, если файл базы данных синхронизируется, поскольку часть мультибазы данных передает, аргумент указывает на nul-законченную последовательность, содержащую операционное имя файла супержурнала. VFS, которым не нужен этот сигнал, должны тихо проигнорировать этот код операции. Приложения не должны вызывать sqlite3_file_control() с этим кодом операции, поскольку выполнение этого может разрушить работу специализированных VFS, которые действительно требуют его.

• SQLITE_FCNTL_COMMIT_PHASETWO произведен внутренне SQLite и послан в VFS после того, как транзакция была немедленно передана, но прежде чем базу данных открывают. VFS, которым не нужен этот сигнал, должны тихо проигнорировать этот код операции. Приложения не должны вызывать sqlite3_file_control() с этим кодом операции, поскольку выполнение этого может разрушить работу специализированных VFS, которые действительно требуют его.

• SQLITE_FCNTL_WIN32_AV_RETRY используется, чтобы формировать автоматическое количество повторных попыток и интервалы для определенной дисковой операции I/O для windows VFS, чтобы обеспечить надежность в присутствии антивирусных программ. По умолчанию windows VFS повторит чтение, запись и удаление файла до 10 раз с задержкой 25 миллисекунд перед первой повторной попыткой и с задержкой, увеличивающейся еще на 25 миллисекунд с каждой последующей повторной попыткой. Этот код операции позволяет этим двум значениям (10 повторений и 25 миллисекунд задержки) быть пренастроенными. Значения изменяются для всех соединений с базой данных в рамках того же самого процесса. Аргумент это указатель на множество двух целых чисел, где первое целое число это новое количество повторных попыток, второе целое число задержка. Если любое целое число отрицательно, то настройки не изменяются, но вместо этого предшествующее значение написано в запись массива, позволив текущим параметрам настройки повторной попытки быть опрошенными. Параметр zDbName игнорируется.

• SQLITE_FCNTL_PERSIST_WAL используется, чтобы установить или запрость постоянное значение журнала с упреждающей записью. По умолчанию вспомогательный журнал с упреждающей записью (WAL-файл) и файлы общей памяти, используемые для управления транзакциями, автоматически удалены, когда последняя связь с базой данных закрывается. Урегулирование постоянного режима WAL заставляет те файлы сохраняться после закрытия. Упорство файлов полезно, когда другие процессы, которые не имеют права записи на каталог, содержащий файл базы данных, хотят прочитать файл базы данных, поскольку WAL и файлы общей памяти должны существовать для базы данных, чтобы быть читаемыми. Четвертый параметр sqlite3_file_control() для этого кода операции должен быть указателем на целое число. Это целое число 0, чтобы отключить постоянный режим WAL или 1, чтобы позволить постоянный режим WAL. Если целое число -1, то оно переписано текущим значением.

• SQLITE_FCNTL_POWERSAFE_OVERWRITE используется, чтобы установить или запросить постоянное "powersafe-overwrite" или "PSOW". PSOW определяет часть битов SQLITE_IOCAP_POWERSAFE_OVERWRITE методов xDeviceCharacteristics. Четвертый параметр sqlite3_file_control() для этого кода операции должен быть указателем на целое число. То целое число 0, чтобы отключить режим нулевого повреждения или 1, чтобы позволить режим. Если целое число -1, то оно переписано текущим значением.

• SQLITE_FCNTL_OVERWRITE вызван SQLite после открытия транзакции записи, чтобы указать, что, если это не отменено по некоторым причинам, весь файл базы данных будет переписан текущей транзакцией. Это используется операциями VACUUM.

• SQLITE_FCNTL_VFSNAME может использоваться, чтобы получить названия всех VFSes в стеке VFS. Имена имеют всех VFS написаны в память, полученную из sqlite3_malloc(), результат сохранен в переменной char*, на которую указывает четвертый параметр sqlite3_file_control(). Вызывающий ответственен за освобождение памяти, когда все сделано. Как со всеми действиями контроля файла, нет никакой гарантии, что это на самом деле сделает что-либо. Вызывающий должен инициализировать переменную char* = NULL в случае, если этот контроль файла не осуществляется. Этот контроль файла предназначается только для диагностического использования.

• SQLITE_FCNTL_VFS_POINTER считает указатель на VFS верхнего уровня использующимся в настоящее время. Аргумент X в sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) должен быть типа "sqlite3_vfs **". Этот код операции установит *X в указатель на VFS верхнего уровня. Когда есть многократные прокладки VFS в стеке, этот код операции находит только высшую прокладку.

• Каждый раз, когда PRAGMA размечено, контроль за файлом SQLITE_FCNTL_PRAGMA посылают в открытый объект sqlite3_file, соответствующий файлу базы данных, к которому относится запрос pragma. Аргумент контроля за файлом SQLITE_FCNTL_PRAGMA это множество указателей на последовательности (char**), в котором второй элемент множества это название pragma, а третий элемент аргумент pragma или NULL, если у pragma нет аргумента. Обработчик для контроля за файлом SQLITE_FCNTL_PRAGMA может произвольно сделать первый элемент char** аргументом последовательности, полученной из sqlite3_mprintf() или эквивалент и эта последовательность станет результатом pragma или сообщением об ошибке, если pragma потерпит неудачу. Если контроль за файлом SQLITE_FCNTL_PRAGMA вернет SQLITE_NOTFOUND, то нормальная обработка PRAGMA продолжается. Если контроль за файлом SQLITE_FCNTL_PRAGMA вернет SQLITE_OK, то анализатор предполагает, что VFS обращался с самим PRAGMA, и анализатор не производит никакой подготовленный запрос, если последовательность результата NULL, или это возвращает копию последовательности результата, если последовательность не-NULL. Если контроль за файлом SQLITE_FCNTL_PRAGMA возвращает какой-либо код результата кроме SQLITE_OK или SQLITE_NOTFOUND, это означает, что VFS столкнулся с ошибкой, обращаясь к PRAGMA и компиляция PRAGMA терпит неудачу с ошибкой. Контроль за файлом SQLITE_FCNTL_PRAGMA происходит в начале анализа pragma и таким образом, это в состоянии отвергнуть встроенные запросы PRAGMA.

• SQLITE_FCNTL_BUSYHANDLER может быть вызван SQLite на дескрипторе файла базы данных вскоре после того, как это открыто, чтобы предоставить VFS доступ к отзыву занятого обработчика связи. Аргумент имеет тип (void**), это массив из двух значений (void *). Первый (void *) на самом деле указывает на функцию типа (int (*)(void *)). Чтобы вызвать занятого обработчика связи, эта функция должна быть вызвана со вторым (void *) со множеством как единственный аргумент. Если это возвращает отличное от нуля, то операция должна быть повторена. Если это возвращает ноль, VFS должен оставить текущую операцию.

• Приложения могут вызвать контроль файла SQLITE_FCNTL_TEMPFILENAME, чтобы SQLite производил временное имя файла, используя тот же самый алгоритм, который сопровождается, чтобы произвести временные имена файлов для таблиц TEMP и других внутренних задач. Аргумент должен быть char**, который будет заполнен именем файла, написанным в память, полученную из sqlite3_malloc(). Вызывающий должен вызвать sqlite3_free(), чтобы избежать утечки памяти.

• SQLITE_FCNTL_MMAP_SIZE используется, чтобы запросить или определить максимальное число байтов, которое будет использоваться для I/O с отображенной памятью. Аргумент это указатель на значение типа sqlite3_int64, является консультативным максимальным количеством байтов в файле для карты распределения памяти. Указатель переписан старым значением. Предел не изменяется, если указано негативное значение, таким образом, текущий предел может быть запрошен, передав указатель на отрицательное число. Этот контроль файла используется внутренне, чтобы осуществить PRAGMA mmap_size.

• SQLITE_FCNTL_TRACE предоставляет консультативную информацию VFS о том, что делают более высокие слои стека SQLite. Этот контроль за файлом используется некоторыми поисковыми shims деятельности VFS. Аргумент это законченная нолем последовательность. Более высокие слои в стеке SQLite могут произвести экземпляры этого контроля за файлом, если включен выбор времени компиляции SQLITE_USE_FCNTL_TRACE.

• SQLITE_FCNTL_HAS_MOVED интерпретирует свой аргумент как указатель на целое число, и он пишет boolean в этот integer в зависимости от того, был ли файл переименован, перемещен или удален после его первого открытия.

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

• SQLITE_FCNTL_WIN32_SET_HANDLE используется для отладки. Этот код операции заставляет метод xFileControl обменивать дескриптор файла с тем, на который указывает аргумент pArg. Это используется во время тестирования и должно быть поддержано только когда SQLITE_TEST определяется.

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

• SQLITE_FCNTL_ZIPVFS осуществляется только zipvfs. Все другие VFS должен возвратить SQLITE_NOTFOUND для этого кода операции.

• SQLITE_FCNTL_RBU осуществляется специальным VFS, используемым только расширением RBU. Все другие VFS должен возвратить SQLITE_NOTFOUND для этого кода операции.

• Если SQLITE_FCNTL_BEGIN_ATOMIC_WRITE вернет SQLITE_OK, то дескриптор файла помещается в "batch write mode", что означает, что все последующие операции записи будут отсрочены и сделаны атомарно в следующем SQLITE_FCNTL_COMMIT_ATOMIC_WRITE. Системы, которые не поддерживают атомную пакетную запись, возвратят SQLITE_NOTFOUND. После успешного SQLITE_FCNTL_BEGIN_ATOMIC_WRITE и до закрытия SQLITE_FCNTL_COMMIT_ATOMIC_WRITE или SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE SQLite не вызовет интерфейс VFS, который обращается к тому же самому дескриптору файла sqlite3_file за исключением вызовов методов xWrite и xFileControl с SQLITE_FCNTL_SIZE_HINT.

• SQLITE_FCNTL_COMMIT_ATOMIC_WRITE заставляет все операции записи, начиная с предыдущего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE быть выполненными атомарно. Этот контроль за файлом возвращает SQLITE_OK если и только если запись была вся выполнено успешно. Независимо от того, успешно ли это, этот контроль за файлом выводит дескриптор файла из пакетного режима записи так, чтобы все последующие операции записи были независимы. SQLite никогда не будет вызывать SQLITE_FCNTL_COMMIT_ATOMIC_WRITE без предшествующего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.

• SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE заставляет все операции записи, начиная с предыдущего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE отмениться. Этот контроль за файлом выводит дескриптор файла из пакетного режима записи так, чтобы все последующие операции записи были независимы. SQLite никогда не будет вызовать SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE без предшествующего успешного вызова SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.

• SQLITE_FCNTL_LOCK_TIMEOUT используется, чтобы формировать VFS так, чтобы заблокировать на M миллисекунд прежде, чем потерпеть неудачу, пытаясь получить блокировку файла, используя методы xLock или xShmLock VFS. Параметр это указатель на 32-битное целое число со знаком, которое содержит значение, в которое должен быть установлен M. Перед возвращением 32-битное целое число со знаком переписано предыдущим значением M.

• SQLITE_FCNTL_DATA_VERSION используется, чтобы обнаружить изменения файла базы данных. Аргумент это указатель на 32-битное целое без знака. "Версия данных" для страниц написана в указатель. "Версия данных" изменяется каждый раз, когда любое изменение происходит с соответствующим файлом базы данных через SQL-операторы на том же самом соединении с базой данных или через транзакции, переданные отдельными соединениями с базой данных возможно в других процессах. sqlite3_total_changes() может использоваться, чтобы найти, изменилась ли какая-либо база данных по связи, но интерфейс отвечает на изменения на TEMP, а также MAIN и не обеспечивает механизм, чтобы обнаружить только изменения MAIN. Кроме того, sqlite3_total_changes() отвечает только на внутренние изменения и опускает изменения, внесенные другими соединениями с базой данных. PRAGMA data_version обеспечивает механизм, чтобы обнаружить изменения единственной базы данных, которые происходят из-за других соединений с базой данных, но опускает изменения, осуществленные соединением с базой данных, на котором это вызывают. Этот контроль за файлом это единственный механизм, чтобы обнаружить изменения, которые происходят внутренне или внешне и связаны с конкретной базой данных.

• SQLITE_FCNTL_CKPT_START вызван из контрольной точки в wal-режиме, прежде чем клиент начнет копировать страницы от wal-файла в файл базы данных.

• SQLITE_FCNTL_CKPT_DONE вызван из контрольной точки в wal-режиме после того, как клиент закончил копировать страницы от wal-файла до файла базы данных, но перед обновлением файла *-shm, чтобы сделать запись того, что страницы были сохранены.

• SQLITE_FCNTL_EXTERNAL_READER используется, чтобы обнаружить, есть ли клиент базы данных в другом процессе с транзакцией wal-режима, открытой на базе данных или нет. Это доступно только на Unix. Параметр (void*), переданный с этим контролем файла, должен быть указателем на значение типа (int). Целочисленное значение установлено в 1, если база данных это база данных в режиме wal, и там существует по крайней мере один клиент в другом процессе, у которого в настоящее время есть транзакция SQL, открытая на базе данных. Это установлено в 0, если база данных не в wal-режиме или если нет такой связи ни в каком другом процессе. Этот код операции не может использоваться, чтобы обнаружить транзакции, открытые клиентами в рамках текущего процесса, только в рамках других процессов.

• SQLITE_FCNTL_CKSM_FILE только для использования внутренне checksum VFS shim.

• Если в настоящее время нет никакой транзакции, открытой на базе данных, и база данных не temp, SQLITE_FCNTL_RESET_CACHE производит чистку содержания кэша в странице db temp, этот код операции не делает ничего.

Виртуальные коды ограничивающего оператора таблицы

#define SQLITE_INDEX_CONSTRAINT_EQ          2
#define SQLITE_INDEX_CONSTRAINT_GT          4
#define SQLITE_INDEX_CONSTRAINT_LE          8
#define SQLITE_INDEX_CONSTRAINT_LT         16
#define SQLITE_INDEX_CONSTRAINT_GE         32
#define SQLITE_INDEX_CONSTRAINT_MATCH      64
#define SQLITE_INDEX_CONSTRAINT_LIKE       65
#define SQLITE_INDEX_CONSTRAINT_GLOB       66
#define SQLITE_INDEX_CONSTRAINT_REGEXP     67
#define SQLITE_INDEX_CONSTRAINT_NE         68
#define SQLITE_INDEX_CONSTRAINT_ISNOT      69
#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL  70
#define SQLITE_INDEX_CONSTRAINT_ISNULL     71
#define SQLITE_INDEX_CONSTRAINT_IS         72
#define SQLITE_INDEX_CONSTRAINT_LIMIT      73
#define SQLITE_INDEX_CONSTRAINT_OFFSET     74
#define SQLITE_INDEX_CONSTRAINT_FUNCTION  150

Эти макросы определяют позволенные значения для поля sqlite3_index_info.aConstraint[].op. Каждое значение представляет оператор, который является частью ограничительного срока в операторе WHERE запроса, который использует виртуальную таблицу.

Левый операнд оператора дан соответствующему полю aConstraint[].iColumn. iColumn = -1 указывает, что левый операнд это rowid. У SQLITE_INDEX_CONSTRAINT_LIMIT и SQLITE_INDEX_CONSTRAINT_OFFSET нет левого операнда, таким образом для тех операторов соответствующее поле aConstraint[].iColumn бессмысленно и не должно использоваться.

Все значения оператора от SQLITE_INDEX_CONSTRAINT_FUNCTION до значения 255 резервируются, чтобы представлять функции, которые перегружены методом xFindFunction виртуального внедрения таблицы.

Правые операнды для каждого ограничения могли бы быть доступны через sqlite3_vtab_rhs_value(). Обычно правый операнд доступен только, если это появляется как единственный постоянный литерал во входе SQL. Если правый операнд будет другой колонкой или выражением (даже константным выражением) или параметром, то sqlite3_vtab_rhs_value(), вероятно, не будет в состоянии извлечь его. У операторов SQLITE_INDEX_CONSTRAINT_ISNULL и SQLITE_INDEX_CONSTRAINT_ISNOTNULL нет правого операнда, следовательно sqlite3_vtab_rhs_value() для тех операторов будет всегда возвращать SQLITE_NOTFOUND.

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

Характеристики устройства

#define SQLITE_IOCAP_ATOMIC                 0x00000001
#define SQLITE_IOCAP_ATOMIC512              0x00000002
#define SQLITE_IOCAP_ATOMIC1K               0x00000004
#define SQLITE_IOCAP_ATOMIC2K               0x00000008
#define SQLITE_IOCAP_ATOMIC4K               0x00000010
#define SQLITE_IOCAP_ATOMIC8K               0x00000020
#define SQLITE_IOCAP_ATOMIC16K              0x00000040
#define SQLITE_IOCAP_ATOMIC32K              0x00000080
#define SQLITE_IOCAP_ATOMIC64K              0x00000100
#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
#define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
#define SQLITE_IOCAP_IMMUTABLE              0x00002000
#define SQLITE_IOCAP_BATCH_ATOMIC           0x00004000

Метод xDeviceCharacteristics объекта sqlite3_io_methods возвращает целое число, которое является вектором этих разрядных значений, выражающих особенности I/O устройства массового хранения, которое содержит файл, к которому относится sqlite3_io_methods.

SQLITE_IOCAP_ATOMIC означает, что все записи атомные. Значения SQLITE_IOCAP_ATOMICnnn значат, что записи блоков, которые nnn байт размером и выровнены с адресом, который является целым числом, кратным nnn, атомны. SQLITE_IOCAP_SAFE_APPEND означает, что, когда данные добавлены к файлу, данные сначала пишутся, потом меняется размер файла, никогда наоборот. SQLITE_IOCAP_SEQUENTIAL означает, что информация написана на диск в том же самом порядке, как вызывали xWrite(). SQLITE_IOCAP_POWERSAFE_OVERWRITE означает, что после перезагрузки после катастрофы или потери питания единственные байты в файле, которые были написаны на уровне приложения, возможно, изменились и что смежные байты, даже байты в том же самом секторе, как гарантируют, будут неизменны. Флаг SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN указывает, что файл не может быть удален, когда открыт. SQLITE_IOCAP_IMMUTABLE указывает, что файл находится на носителе только для чтения и не может быть изменен даже процессами с поднятыми привилегиями.

SQLITE_IOCAP_BATCH_ATOMIC означает, что основная файловая система поддерживает выполнение многократных операций записи атомарно, когда те операции записи заключены в скобки SQLITE_FCNTL_BEGIN_ATOMIC_WRITE и SQLITE_FCNTL_COMMIT_ATOMIC_WRITE.

Уровни блокировки файла

#define SQLITE_LOCK_NONE          0       /* xUnlock() only */
#define SQLITE_LOCK_SHARED        1       /* xLock() or xUnlock() */
#define SQLITE_LOCK_RESERVED      2       /* xLock() only */
#define SQLITE_LOCK_PENDING       3       /* xLock() only */
#define SQLITE_LOCK_EXCLUSIVE     4       /* xLock() only */

SQLite использует одно из этих целочисленных значений как второй аргумент вызовам, которые используют методы xLock() и xUnlock() объекта sqlite3_io_methods. Эти значения упорядочены от менее строгого к самому строгому.

Аргументом xLock() всегда является SHARED или выше. Аргумент xUnlock SHARED или NONE.

Типы Mutex

#define SQLITE_MUTEX_FAST             0
#define SQLITE_MUTEX_RECURSIVE        1
#define SQLITE_MUTEX_STATIC_MAIN      2
#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_randomness() */
#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
#define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */
#define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */
#define SQLITE_MUTEX_STATIC_APP1      8  /* For use by application */
#define SQLITE_MUTEX_STATIC_APP2      9  /* For use by application */
#define SQLITE_MUTEX_STATIC_APP3     10  /* For use by application */
#define SQLITE_MUTEX_STATIC_VFS1     11  /* For use by built-in VFS */
#define SQLITE_MUTEX_STATIC_VFS2     12  /* For use by extension VFS */
#define SQLITE_MUTEX_STATIC_VFS3     13  /* For use by application VFS */

sqlite3_mutex_alloc() берет отдельный аргумент, который является одной из этих констант целого числа.

Набор статического mutexes может измениться от одного выпуска SQLite до следующего. Запросы, которые отвергают встроенную mutex логику, должны быть готовы обработать дополнительный статический mutexes.

Флаги для операций открытия файла

#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
#define SQLITE_OPEN_SUPER_JOURNAL    0x00004000  /* VFS only */
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
#define SQLITE_OPEN_NOFOLLOW         0x01000000  /* Ok for sqlite3_open_v2() */
#define SQLITE_OPEN_EXRESCODE        0x02000000  /* Extended result codes */

Эти битовые значения предназначаются для использования в 3-м параметре sqlite3_open_v2() и в 4-м параметре метода sqlite3_vfs.xOpen.

Только те флаги, отмеченные как "Ok for sqlite3_open_v2()", могут использоваться в качестве третьего аргумента sqlite3_open_v2(). Другие флаги были исторически проигнорированы sqlite3_open_v2(), хотя будущие версии SQLite могли бы измениться так, чтобы ошибка была поднята, если какой-либо из отвергнутых битов передается в sqlite3_open_v2(). Приложения не должны зависеть от исторического поведения.

Отметьте в особенности, что прохождение флага SQLITE_OPEN_EXCLUSIVE в sqlite3_open_v2() НЕ заставляет открыть основной файл базы данных, используя O_EXCL. Прохождение SQLITE_OPEN_EXCLUSIVE в sqlite3_open_v2() исторически не делает ничего и могло бы стать ошибкой в будущих версиях SQLite.

Подготовленные флаги

#define SQLITE_PREPARE_PERSISTENT              0x01
#define SQLITE_PREPARE_NORMALIZE               0x02
#define SQLITE_PREPARE_NO_VTAB                 0x04

Эти константы определяют различные флаги, которые могут быть переданы в параметр "prepFlags" в sqlite3_prepare_v3() и sqlite3_prepare16_v3().

Новые флаги могут быть добавлены в будущих выпусках SQLite.

SQLITE_PREPARE_PERSISTENT

SQLITE_PREPARE_PERSISTENT это намек планировщику запроса, что подготовленный запрос будет сохраняться в течение долгого времени и вероятно много раз снова использоваться. Без этого флага sqlite3_prepare_v3() и sqlite3_prepare16_v3() предполагают, что подготовленный запрос будет использоваться только однажды или самое большее несколько раз и затем разрушен использованием sqlite3_finalize() относительно скоро. Текущее внедрение действует на этот намек, избегая использования сохраняющей памяти , чтобы не исчерпать ограниченный запас сохраняющей памяти. Будущие версии SQLite могут действовать на этот намек по-другому.

SQLITE_PREPARE_NORMALIZE

SQLITE_PREPARE_NORMALIZE не делает ничего. Этот флаг раньше требовался для любого подготовленного запроса, который хотел использовать sqlite3_normalized_sql(). Но sqlite3_normalized_sql() теперь доступен всем подготовленным запросам, независимо от того, используют ли они этот флаг.

SQLITE_PREPARE_NO_VTAB

SQLITE_PREPARE_NO_VTAB заставляет компилятор SQL возвращать ошибку (код ошибки SQLITE_ERROR), если запрос использует какие-либо виртуальные таблицы.

Подготовленный статус просмотра запроса

#define SQLITE_SCANSTAT_COMPLEX 0x0001

Подготовленные коды операции статуса просмотра запроса

#define SQLITE_SCANSTAT_NLOOP    0
#define SQLITE_SCANSTAT_NVISIT   1
#define SQLITE_SCANSTAT_EST      2
#define SQLITE_SCANSTAT_NAME     3
#define SQLITE_SCANSTAT_EXPLAIN  4
#define SQLITE_SCANSTAT_SELECTID 5
#define SQLITE_SCANSTAT_PARENTID 6
#define SQLITE_SCANSTAT_NCYCLE   7

Следующие константы могут быть применены для параметра T в sqlite3_stmt_scanstatus(S,X,T,V). Каждая константа определяет различную метрику для возврата sqlite3_stmt_scanstatus().

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

Не все значения доступны для всех элементов запроса. Когда значение недоступно, выходная переменная установлена в -1, если значение числовое, или в NULL, если это последовательность (SQLITE_SCANSTAT_NAME).

SQLITE_SCANSTAT_NLOOP

sqlite3_int64 это переменная, на которую указывает V параметр, будет установлена в общее количество времени, которое работал X-й цикл.

SQLITE_SCANSTAT_NVISIT

sqlite3_int64 это переменная, на которую указывает V параметр, будет установлена в общее количество строк, исследованных всеми повторениями X-го цикла.

SQLITE_SCANSTAT_EST

Переменная "double", на которую указывает параметр V, будет установлена в оценку планировщика запроса для среднего количества вывода строк от каждого повторения цикла X. Если оценки планировщика запроса были точны, то это значение приблизительно NVISIT/NLOOP и произведение этого значения для всех предшествующих циклов аналогично SELECTID и NLOOP для текущей итерации.

SQLITE_SCANSTAT_NAME

Переменная "const char *", на которую указывает параметр V, будет установлена в законченную нолем последовательность UTF-8, содержащую название индекса или таблицы, используемого для цикла X.

SQLITE_SCANSTAT_EXPLAIN

Переменная "const char *", на которую указывает параметр V, будет установлена в законченную нолем последовательность UTF-8, содержащую описание EXPLAIN QUERY PLAN для цикла X.

SQLITE_SCANSTAT_SELECTID

Переменная "int", на которую указывает параметр V, будет установлена в id для элемента плана запросов X. id уникально в рамках запроса. select-id та же самая величина, как произведенная в первой колонке запроса EXPLAIN QUERY PLAN.

SQLITE_SCANSTAT_PARENTID

Переменная "int", на которую указывает параметр V, будет установлена в id родителя текущего элемента запроса, если возможно, или к нолю, если у элемента запроса не будет родителя. Это то же самое значение, как возвращено во второй колонке запроса EXPLAIN QUERY PLAN.

SQLITE_SCANSTAT_NCYCLE

Выходное значение sqlite3_int64 установлено в количество циклов, согласно счетчику метки времени процессора, которое прошло в то время, как элемент запроса обрабатывался. Это значение недоступно для всех элементов запроса, если это недоступно, выходная переменная установлена в -1.

Флаги для метода xShmLock VFS

#define SQLITE_SHM_UNLOCK       1
#define SQLITE_SHM_LOCK         2
#define SQLITE_SHM_SHARED       4
#define SQLITE_SHM_EXCLUSIVE    8

Эти константы целого числа определяют различные операции по блокировке, позволенные методу xShmLock sqlite3_io_methods . Следующее это единственные легальные комбинации флагов метода xShmLock:

• SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
• SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
• SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
• SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE

Разблокируя, тот же самый флаг SHARED или EXCLUSIVE должны поставляться, как было дано на соответствующей блокировке.

Метод xShmLock может перейти между разблокированным и SHARED или разблокированным и EXCLUSIVE. Это не может перейти между SHARED и EXCLUSIVE.

Номера версий библиотеки времени компиляции

#define SQLITE_VERSION        "3.44.0"
#define SQLITE_VERSION_NUMBER 3044000
#define SQLITE_SOURCE_ID "2023-11-01 11:23:50 17129ba1ff7f0daf37100ee82d507aef7827cf38de1866e2633096ae6ad81301"

C-макрос SQLITE_VERSION препроцессора в заголовочном файле sqlite3.h оценивается к строковому литералу, который является версией SQLite в формате "X.Y.Z", где X это номер основной версии (всегда 3 для SQLite3), Y номер вспомогательной версии, а Z номер выпуска. C-макрос SQLITE_VERSION_NUMBER препроцессора решается к целому числу со значением (X*1000000 + Y*1000 + Z), где X, Y и Z являются теми же самыми числами, используемыми в SQLITE_VERSION. SQLITE_VERSION_NUMBER для любого данного выпуска SQLite также будет больше, чем выпуск, из которого это получено. Или Y будет считаться постоянным, а Z будет увеличен, иначе Y будет увеличен, а Z будет сброшен к нолю.

Начиная с version 3.6.18 (2009-09-11), исходные тексты SQLite были сохранены в Fossil configuration management system. Макрос SQLITE_SOURCE_ID оценивается к последовательности, которая определяет конкретную регистрацию SQLite в системе управления конфигурацией. Последовательность SQLITE_SOURCE_ID содержит дату и время регистрации (UTC) и хэш SHA1 или SHA3-256 всего исходного дерева. Если исходный код был отредактирован в каком-либо случае, так как в нем в последний раз зарегистрировались, то последние четыре шестнадцатеричных цифры хэша могут быть изменены.

См. также: sqlite3_libversion(), sqlite3_libversion_number(), sqlite3_sourceid(), sqlite_version() и sqlite_source_id().

Константы, определяющие специальное поведение деструктора

typedef void (*sqlite3_destructor_type)(void*);
#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)

Это специальные значения для деструктора, которые передаются как заключительный аргумент функциям типа sqlite3_result_blob(). Если аргумент деструктора SQLITE_STATIC, это означает, что указатель содержания постоянный и никогда не будет изменяться. Это не должно быть разрушено. Значение SQLITE_TRANSIENT означает, что содержание, вероятно, изменится в ближайшем будущем и что SQLite должен сделать свою собственную частную копию содержания перед возвращением.

Определение типа необходимо, чтобы решить проблему в определенных компиляторах C++.

Параметры статуса

#define SQLITE_STATUS_MEMORY_USED          0
#define SQLITE_STATUS_PAGECACHE_USED       1
#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
#define SQLITE_STATUS_SCRATCH_USED         3  /* NOT USED */
#define SQLITE_STATUS_SCRATCH_OVERFLOW     4  /* NOT USED */
#define SQLITE_STATUS_MALLOC_SIZE          5
#define SQLITE_STATUS_PARSER_STACK         6
#define SQLITE_STATUS_PAGECACHE_SIZE       7
#define SQLITE_STATUS_SCRATCH_SIZE         8  /* NOT USED */
#define SQLITE_STATUS_MALLOC_COUNT         9

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

SQLITE_STATUS_MEMORY_USED

Этот параметр это проверенное использование текущего объема памяти sqlite3_malloc(), прямо или косвенно. Число включает вызовы sqlite3_malloc() и использование внутренней памяти библиотекой SQLite. Вспомогательная кэш-память страниц, которой управляет SQLITE_CONFIG_PAGECACHE, не включена в этот параметр. Возвращенная сумма является суммой размеров распределения, как сообщается методом xSize в sqlite3_mem_methods.

SQLITE_STATUS_MALLOC_SIZE

Этот параметр делает запись самого большого запроса выделения памяти через sqlite3_malloc() или sqlite3_realloc() (или их внутренними эквивалентами). Только значение, возвращенное sqlite3_status() представляет интерес. Значение, которое вписывают в *pCurrent, неопределено.

SQLITE_STATUS_MALLOC_COUNT

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

SQLITE_STATUS_PAGECACHE_USED

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

SQLITE_STATUS_PAGECACHE_OVERFLOW

Этот параметр возвращает число байтов распределения кэша страницы, которое не могло быть удовлетворено буфером SQLITE_CONFIG_PAGECACHE и где вызвано переполнение к sqlite3_malloc(). Возвращенная значение включает отчисления, которые переполнились, потому что они слишком большие (они были больше, чем параметр "sz" в SQLITE_CONFIG_PAGECACHE) и отчисления, которые переполнились, потому что места не оставалось в кэше страницы.

SQLITE_STATUS_PAGECACHE_SIZE

Этот параметр делает запись самого большого запроса выделения памяти через распределитель памяти. Только значение, возвращенное в *pHighwater параметре sqlite3_status() важно. Значение *pCurrent неопределено.

SQLITE_STATUS_SCRATCH_USED

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

SQLITE_STATUS_SCRATCH_OVERFLOW

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

SQLITE_STATUS_SCRATCH_SIZE

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

SQLITE_STATUS_PARSER_STACK

*pHighwater делает запись самого глубокого стека анализатора. *pCurrent неопределено. *pHighwater значащее только если SQLite собран с YYTRACKMAXSTACKDEPTH.

Новые параметры статуса могут время от времени добавляться.

Флаги типа синхронизации

#define SQLITE_SYNC_NORMAL        0x00002
#define SQLITE_SYNC_FULL          0x00003
#define SQLITE_SYNC_DATAONLY      0x00010

Когда SQLite вызывает метод xSync() объекта sqlite3_io_methods, это использует комбинацию этих целочисленных значений как второй аргумент.

Когда флаг SQLITE_SYNC_DATAONLY используется, это означает, что синхронизирующая операция должна только сбросить данные на диск. Информация о Inode не должна сброситься. Если нижние четыре бита флага равняются SQLITE_SYNC_NORMAL, это означает использовать нормальный fsync(). Если нижние четыре бита флага равняются SQLITE_SYNC_FULL, это означает использовать стиль Mac OS X fullsync вместо fsync().

Не путайте флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL с с PRAGMA synchronous=NORMAL и PRAGMA synchronous=FULL. Синхронные прагмы определяют, когда обращения к методу xSync VFS происходят, и применяется однородно для всех платформ. Флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL определяют, насколько строги синхронизирующие операции и имеют значение только на MAC OSX для кода SQLite по умолчанию. Сторонние внедрения VFS могли бы также сделать различие между SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL, но среди операционных систем, изачально поддерживаемых SQLite, только Mac OSX это делает.

Тестирование интерфейсных кодов операций

#define SQLITE_TESTCTRL_FIRST                    5
#define SQLITE_TESTCTRL_PRNG_SAVE                5
#define SQLITE_TESTCTRL_PRNG_RESTORE             6
#define SQLITE_TESTCTRL_PRNG_RESET               7  /* NOT USED */
#define SQLITE_TESTCTRL_FK_NO_ACTION             7
#define SQLITE_TESTCTRL_BITVEC_TEST              8
#define SQLITE_TESTCTRL_FAULT_INSTALL            9
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
#define SQLITE_TESTCTRL_PENDING_BYTE            11
#define SQLITE_TESTCTRL_ASSERT                  12
#define SQLITE_TESTCTRL_ALWAYS                  13
#define SQLITE_TESTCTRL_RESERVE                 14  /* NOT USED */
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
#define SQLITE_TESTCTRL_ISKEYWORD               16  /* NOT USED */
#define SQLITE_TESTCTRL_SCRATCHMALLOC           17  /* NOT USED */
#define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS      17
#define SQLITE_TESTCTRL_LOCALTIME_FAULT         18
#define SQLITE_TESTCTRL_EXPLAIN_STMT            19  /* NOT USED */
#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD    19
#define SQLITE_TESTCTRL_NEVER_CORRUPT           20
#define SQLITE_TESTCTRL_VDBE_COVERAGE           21
#define SQLITE_TESTCTRL_BYTEORDER               22
#define SQLITE_TESTCTRL_ISINIT                  23
#define SQLITE_TESTCTRL_SORTER_MMAP             24
#define SQLITE_TESTCTRL_IMPOSTER                25
#define SQLITE_TESTCTRL_PARSER_COVERAGE         26
#define SQLITE_TESTCTRL_RESULT_INTREAL          27
#define SQLITE_TESTCTRL_PRNG_SEED               28
#define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS     29
#define SQLITE_TESTCTRL_SEEK_COUNT              30
#define SQLITE_TESTCTRL_TRACEFLAGS              31
#define SQLITE_TESTCTRL_TUNE                    32
#define SQLITE_TESTCTRL_LOGEST                  33
#define SQLITE_TESTCTRL_USELONGDOUBLE           34
#define SQLITE_TESTCTRL_LAST                    34  /* Largest TESTCTRL */

Эти константы это действительные параметры кода операции, используемые в качестве первого аргумента sqlite3_test_control().

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

Коды события SQL Trace

#define SQLITE_TRACE_STMT       0x01
#define SQLITE_TRACE_PROFILE    0x02
#define SQLITE_TRACE_ROW        0x04
#define SQLITE_TRACE_CLOSE      0x08

Эти константы определяют классы событий, которые могут следить за развитием, используя sqlite3_trace_v2(). Аргумент M в sqlite3_trace_v2(D,M,X,P) это OR-комбинация одной или больше следующих констант. Первый аргумент отзыва трассировки это одна из следующих констант.

Новые поисковые константы могут быть добавлены в будущих выпусках.

У отзыва есть четыре аргумента: xCallback(T,C,P,X). Аргумент T это один из кодов целого типа выше. Аргумент C это копия указателя контекста, переданного как четвертый аргумент sqlite3_trace_v2(). Аргументы P и X это указатели, значения которых зависят от T.

SQLITE_TRACE_STMT

Отзыв SQLITE_TRACE_STMT вызван, когда подготовленный запрос сначала начинает работать и возможно в других случаях во время выполнения подготовленного запроса, например, в начале каждого триггера. Аргумент P это указатель на подготовленный запрос. Аргумент X это указатель на последовательность, которая является нерасширенным кодом SQL подготовленного запроса или комментария SQL, который указывает на вызов триггера. Отзыв может вычислить тот же самый текст, который был бы возвращен sqlite3_trace() при помощи аргумента X, когда X начинается с "--", иначе вызывает sqlite3_expanded_sql(P).

SQLITE_TRACE_PROFILE

Отзыв SQLITE_TRACE_PROFILE предоставляет приблизительно ту же самую информацию, как обеспечивается sqlite3_profile(). Аргумент P это указатель на подготовленный запрос, аргумент X указывает на 64-bit integer, которое является приблизительным числом наносекунд, которые подготовленный запрос работал. Отзыв SQLITE_TRACE_PROFILE вызван, когда запрос заканчивается.

SQLITE_TRACE_ROW

Отзыв SQLITE_TRACE_ROW вызван каждый раз, когда подготовленный запрос производит единственную строку результата. Аргумент P это указатель на подготовленный запрос, аргумент X не использован.

SQLITE_TRACE_CLOSE

Отзыв SQLITE_TRACE_CLOSE вызван, когда соединение с базой данных закрывается. Аргумент P это указатель на подготовленный запрос, аргумент X не использован.

Позволенные возвращаемые значения от sqlite3_txn_state()

#define SQLITE_TXN_NONE  0
#define SQLITE_TXN_READ  1
#define SQLITE_TXN_WRITE 2

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

SQLITE_TXN_NONE

SQLITE_TXN_NONE означает, что никакая транзакция в настоящее время не находится на рассмотрении.

SQLITE_TXN_READ

SQLITE_TXN_READ означает, что база данных в настоящее время находится в прочитанной транзакции. Содержание было прочитано из файла базы данных, но ничто в файле базы данных не изменилось. Операционное состояние изменится на SQLITE_TXN_WRITE, если какие-либо изменения произойдут и нет никаких других противоречивых параллельных транзакций записи. Операционное состояние вернется к SQLITE_TXN_NONE после ROLLBACK или COMMIT.

SQLITE_TXN_WRITE

SQLITE_TXN_WRITE означает, что база данных в настоящее время находится в транзакции записи. Содержание было написано файлу базы данных, но еще не передано. Операционное состояние изменится на SQLITE_TXN_NONE в следующем ROLLBACK или COMMIT.

---

Виртуальные параметры конфигурации таблицы

#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
#define SQLITE_VTAB_INNOCUOUS          2
#define SQLITE_VTAB_DIRECTONLY         3
#define SQLITE_VTAB_USES_ALL_SCHEMAS   4

Этот макрос определяет различные варианты sqlite3_vtab_config(), который можно использовать, чтобы настроить и оптимизировать виртуальную таблицу.

SQLITE_VTAB_CONSTRAINT_SUPPORT

Вызов формы sqlite3_vtab_config (db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) поддерживается, где X целое число. Если X ноль, то виртуальная таблица, чей метод xCreate или xConnect вызвал sqlite3_vtab_config(), не поддерживает ограничения. В этой конфигурации (которая является умолчанием), если запрос xUpdate вернет SQLITE_CONSTRAINT, то все запросы отменены, как будто OR ABORT был определен как часть пользовательского SQL-оператора, независимо от фактического ON CONFLICT.

Если X будет отличным от нуля, то виртуальное внедрение таблицы гарантирует, что, если xUpdate вернет SQLITE_CONSTRAINT, это сделает так, прежде чем любые модификации к внутренним или персистентным структурам данных были сделаны. Если ON CONFLICT = ABORT, FAIL, IGNORE или ROLLBACK, SQLite в состоянии отменить запрос или транзакцию базы данных, и оставить или продолжить обрабатывать текущий SQL-оператор. Если ON CONFLICT = REPLACE и xUpdate вернет SQLITE_CONSTRAINT, SQLite обращается с этим, как будто ON CONFLICT был ABORT.

Виртуальные таблицы, которые требуются, чтобы обращаться с OR REPLACE, должны сделать это в рамках метода xUpdate. Если запрос sqlite3_vtab_on_conflict() указывает, что текущая политика ON CONFLICT = REPLACE, виртуальная таблица должна тихо заменить соответствующие строки в отзыве xUpdate и вернуть SQLITE_OK. Или, если это невозможно, это может возвратить SQLITE_CONSTRAINT, в этом случае SQLite отступает к ограничительной обработке OR ABORT.

SQLITE_VTAB_DIRECTONLY

Вызов формы sqlite3_vtab_config (db,SQLITE_VTAB_DIRECTONLY) из методов xConnect или xCreate виртуальной таблицы мешает использовать таблицу из триггеров и обзоров.

SQLITE_VTAB_INNOCUOUS

Вызов формы sqlite3_vtab_config (db,SQLITE_VTAB_INNOCUOUS) из методов xConnect или xCreate виртуальной таблицы определяют, что виртуальная таблица безопасно использовать из триггеров и обзоров. Концептуально, признак SQLITE_VTAB_INNOCUOUS означает, что виртуальная таблица не может причинить серьезный вред, даже если этим управляет злонамеренный хакер. Разработчики должны избежать устанавливать флаг SQLITE_VTAB_INNOCUOUS, если это не абсолютно необходимо.

SQLITE_VTAB_USES_ALL_SCHEMAS

Вызов формы sqlite3_vtab_config (db,SQLITE_VTAB_USES_ALL_SCHEMA) из методов the xConnect или xCreate виртуальной таблицы приказывают планировщику запроса начинать, по крайней мере, транзакцию чтения на всех схемах ("main", "temp" и любая ATTACH-БД) каждый раз, когда виртуальная таблица используется.

---

Директивные типы Win32

#define SQLITE_WIN32_DATA_DIRECTORY_TYPE  1
#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  2

Эти макросы доступны только на Windows. Они определяют позволенные значения для аргумента типа к интерфейсу sqlite3_win32_set_directory.

---

Категории предела во время выполнения

#define SQLITE_LIMIT_LENGTH                    0
#define SQLITE_LIMIT_SQL_LENGTH                1
#define SQLITE_LIMIT_COLUMN                    2
#define SQLITE_LIMIT_EXPR_DEPTH                3
#define SQLITE_LIMIT_COMPOUND_SELECT           4
#define SQLITE_LIMIT_VDBE_OP                   5
#define SQLITE_LIMIT_FUNCTION_ARG              6
#define SQLITE_LIMIT_ATTACHED                  7
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
#define SQLITE_LIMIT_VARIABLE_NUMBER           9
#define SQLITE_LIMIT_TRIGGER_DEPTH            10
#define SQLITE_LIMIT_WORKER_THREADS           11

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

SQLITE_LIMIT_LENGTH

Максимальный размер любой последовательности, BLOB или строки таблицы в байтах.

SQLITE_LIMIT_SQL_LENGTH

Максимальная длина SQL-оператора в байтах.

SQLITE_LIMIT_COLUMN

Максимальное количество колонок в определении таблицы или в наборе результатов SELECT или максимальное количество колонок в индексе, в ORDER BY или GROUP BY.

SQLITE_LIMIT_EXPR_DEPTH

Максимальная глубина дерева синтаксического анализа по любому выражению.

SQLITE_LIMIT_COMPOUND_SELECT

Максимальное количество условий в составном операторе SELECT.

SQLITE_LIMIT_VDBE_OP

Максимальное количество инструкций в программе виртуальной машины. Если sqlite3_prepare_v2() или эквивалент пытается выделить место для большего, чем это значение количества кодов операции в единственном подготовленном запросе, ошибка SQLITE_NOMEM возвращена.

SQLITE_LIMIT_FUNCTION_ARG

Максимальное количество аргументов на функцию.

SQLITE_LIMIT_ATTACHED

Максимальное количество дополнительных БД.

SQLITE_LIMIT_LIKE_PATTERN_LENGTH

Максимальная длина аргумента шаблона операторов LIKE или GLOB.

SQLITE_LIMIT_VARIABLE_NUMBER

Максимальный индекс любого параметра в SQL-операторе.

SQLITE_LIMIT_TRIGGER_DEPTH

Максимальная глубина рекурсии для триггеров.

SQLITE_LIMIT_WORKER_THREADS

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

---

Параметры статуса для соединений с базой данных

#define SQLITE_DBSTATUS_LOOKASIDE_USED       0
#define SQLITE_DBSTATUS_CACHE_USED           1
#define SQLITE_DBSTATUS_SCHEMA_USED          2
#define SQLITE_DBSTATUS_STMT_USED            3
#define SQLITE_DBSTATUS_LOOKASIDE_HIT        4
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
#define SQLITE_DBSTATUS_CACHE_HIT            7
#define SQLITE_DBSTATUS_CACHE_MISS           8
#define SQLITE_DBSTATUS_CACHE_WRITE          9
#define SQLITE_DBSTATUS_DEFERRED_FKS        10
#define SQLITE_DBSTATUS_CACHE_USED_SHARED   11
#define SQLITE_DBSTATUS_CACHE_SPILL         12
#define SQLITE_DBSTATUS_MAX                 12   /* Largest defined DBSTATUS */

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

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

SQLITE_DBSTATUS_LOOKASIDE_USED

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

SQLITE_DBSTATUS_LOOKASIDE_HIT

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

SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE

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

SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL

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

SQLITE_DBSTATUS_CACHE_USED

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

SQLITE_DBSTATUS_CACHE_USED_SHARED

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

SQLITE_DBSTATUS_SCHEMA_USED

Этот параметр возвращает приблизительное количество байтов памяти кучи для хранения схемы для всех баз данных, связанных со связью, main, temp и любые ATTACH-БД. О полном объеме памяти, используемой схемами, сообщают, даже если память схемы разделена с другими соединениями с базой данных из-за включенного общего режима кэширования. Высшая точка, связанная с SQLITE_DBSTATUS_SCHEMA_USED, всегда 0.

SQLITE_DBSTATUS_STMT_USED

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

SQLITE_DBSTATUS_CACHE_HIT

Этот параметр возвращает количество удачных обращений в кэш страниц, которые произошли. Высшая точка, связанная с SQLITE_DBSTATUS_CACHE_HIT, всегда 0.

SQLITE_DBSTATUS_CACHE_MISS

Этот параметр возвращает количество неудачных обращений в кэш страниц, которые произошли. Высшая точка, связанная с SQLITE_DBSTATUS_CACHE_MISS, всегда 0.

SQLITE_DBSTATUS_CACHE_WRITE

Этот параметр возвращает количество грязных записей кэша, которые были написаны на диск. Определенно, число страниц, написанных wal-файлу в базах данных wal-режима или число страниц, написанных файлу базы данных в базах данных режима обратной перемотки. Любые страницы, записанные как часть отката транзакции или операций по восстановлению базы данных, не включены. Если IO или другая ошибка происходят при записи страниц на диск, эффект последующих запросов SQLITE_DBSTATUS_CACHE_WRITE не определен. Высшая точка, связанная с SQLITE_DBSTATUS_CACHE_WRITE, всегда 0.

SQLITE_DBSTATUS_CACHE_SPILL

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

SQLITE_DBSTATUS_DEFERRED_FKS

Этот параметр возвращает ноль для текущего значения если и только если все ограничения внешнего ключа (отсроченные или немедленные) были решены. Высшая точка всегда 0.

---

Параметры статуса для подготовленных запросов

#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
#define SQLITE_STMTSTATUS_SORT              2
#define SQLITE_STMTSTATUS_AUTOINDEX         3
#define SQLITE_STMTSTATUS_VM_STEP           4
#define SQLITE_STMTSTATUS_REPREPARE         5
#define SQLITE_STMTSTATUS_RUN               6
#define SQLITE_STMTSTATUS_FILTER_MISS       7
#define SQLITE_STMTSTATUS_FILTER_HIT        8
#define SQLITE_STMTSTATUS_MEMUSED           99

Эти макросы препроцессора определяет коды целого числа, которые называют значения, связанные с sqlite3_stmt_status() . Значения различных счетчиков следующие:

SQLITE_STMTSTATUS_FULLSCAN_STEP

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

SQLITE_STMTSTATUS_SORT

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

SQLITE_STMTSTATUS_AUTOINDEX

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

SQLITE_STMTSTATUS_VM_STEP

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

SQLITE_STMTSTATUS_REPREPARE

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

SQLITE_STMTSTATUS_RUN

Это число раз выполнения подготовленного запроса. Одно выполнение здесь это вызов sqlite3_step(), сопровождаемый запросом sqlite3_reset(). Счетчик увеличен на первом вызове sqlite3_step() каждого цикла.

SQLITE_STMTSTATUS_FILTER_HIT,
SQLITE_STMTSTATUS_FILTER_MISS

SQLITE_STMTSTATUS_FILTER_HIT показывает сколько раз шаг соединения был обойден потому что фильтр Bloom вернул not-found. Соответствующее значение SQLITE_STMTSTATUS_FILTER_MISS сколько раз фильтр Bloom вернул find и таким образом шаг соединения должен был быть обработан как нормальный.

SQLITE_STMTSTATUS_MEMUSED

Это приблизительное количество байтов памяти кучи, используемой, чтобы сохранить подготовленный запрос. Это значение не счетчик на самом деле и таким образом параметр resetFlg для sqlite3_stmt_status() проигнорирован, когда код операции SQLITE_STMTSTATUS_MEMUSED.

---

Снимок базы данных

typedef struct sqlite3_snapshot {unsigned char hidden[48];} sqlite3_snapshot;

Экземпляр объекта снимка пишет состояние БД WAL-режима для некоторого отдельного момента в истории.

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

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

1 конструктор, использующий этот объект: sqlite3_snapshot_get()

1 деструктор, использующий этот объект: sqlite3_snapshot_free()

3 метода используют этот объект: sqlite3_snapshot_cmp(), sqlite3_snapshot_open(), sqlite3_snapshot_recover()

---

Типы 64-Bit Integer

#ifdef SQLITE_INT64_TYPE
  typedef SQLITE_INT64_TYPE sqlite_int64;
# ifdef SQLITE_UINT64_TYPE
    typedef SQLITE_UINT64_TYPE sqlite_uint64;
# else
    typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
# endif
#elif defined(_MSC_VER) || defined(__BORLANDC__)
  typedef __int64 sqlite_int64;
  typedef unsigned __int64 sqlite_uint64;
#else
  typedef long long int sqlite_int64;
  typedef unsigned long long int sqlite_uint64;
#endif
typedef sqlite_int64 sqlite3_int64;
typedef sqlite_uint64 sqlite3_uint64;

Поскольку нет никакого кросс-платформенного режима, чтобы определить 64-битные целые типы, SQLite включает определения типов для 64-bit signed и unsigned integer.

sqlite3_int64 и sqlite3_uint64 это предпочтительные определения типа. sqlite_int64 и sqlite_uint64 поддерживаются только для обратной совместимости.

sqlite3_int64 и sqlite_int64 могут сохранить целочисленные значения между -9223372036854775808 и +9223372036854775807 включительно. Типы sqlite3_uint64 и sqlite_uint64 могут сохранить целочисленные значения между 0 и +18446744073709551615 включительно.

---

Объект виртуальной таблицы

struct sqlite3_module {
  int iVersion;
  int (*xCreate)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  int (*xDisconnect)(sqlite3_vtab *pVTab);
  int (*xDestroy)(sqlite3_vtab *pVTab);
  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  int (*xClose)(sqlite3_vtab_cursor*);
  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                int argc, sqlite3_value **argv);
  int (*xNext)(sqlite3_vtab_cursor*);
  int (*xEof)(sqlite3_vtab_cursor*);
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  int (*xBegin)(sqlite3_vtab *pVTab);
  int (*xSync)(sqlite3_vtab *pVTab);
  int (*xCommit)(sqlite3_vtab *pVTab);
  int (*xRollback)(sqlite3_vtab *pVTab);
  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
                       void **ppArg);
  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  /* The methods above are in version 1 of the sqlite_module object. Those
  ** below are for version 2 and greater. */
  int (*xSavepoint)(sqlite3_vtab *pVTab, int);
  int (*xRelease)(sqlite3_vtab *pVTab, int);
  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
  /* The methods above are in versions 1 and 2 of the sqlite_module object.
  ** Those below are for version 3 and greater. */
  int (*xShadowName)(const char*);
  /* The methods above are in versions 1 through 3 of the sqlite_module object.
  ** Those below are for version 4 and greater. */
  int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema,
                    const char *zTabName, int mFlags, char **pzErr);
};

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

Виртуальный модуль таблицы создается, заполняя постоянный экземпляр этой структуры и передавая указатель на него в sqlite3_create_module() или sqlite3_create_module_v2(). Регистрация остается действительной, пока она не заменяется другим модулем или пока не закрыто соединение с базой данных. Содержание этой структуры не должно изменяться, в то время как это зарегистрировано в любом соединении с базой данных.

---

Виртуальный объект курсора таблицы

struct sqlite3_vtab_cursor {
  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  /* Virtual table implementations will typically add additional fields */
};

Каждый виртуальный модуль таблицы использует подкласс следующей структуры, чтобы описать курсоры, которые указывают на виртуальную таблицу и используются, чтобы образовать циклы через виртуальную таблицу. Курсоры создаются, используя метод xOpen модуля и разрушены методом xClose. Курсоры используются методами by the xFilter, xNext, xEof, xColumn и xRowid модуля. Каждое внедрение модуля определит содержание структуры курсора, чтобы удовлетворить собственным потребностям.

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

---

Обработчик открытого BLOB

typedef struct sqlite3_blob sqlite3_blob;

Экземпляр этого объекта представляет открытый BLOB, на котором может быть выполнен BLOB I/O. Объекты этого типа созданы sqlite3_blob_open() и разрушены sqlite3_blob_close(). sqlite3_blob_read() и sqlite3_blob_write() может использоваться, чтобы прочитать или написать маленькие подразделы BLOB. sqlite3_blob_bytes() возвращает размер BLOB в байтах.

1 конструктор, использующий этот объект: sqlite3_blob_open()

1 деструктор, использующий этот объект: sqlite3_blob_close()

4 метода используют этот объект: sqlite3_blob_bytes(), sqlite3_blob_read(), sqlite3_blob_reopen() и sqlite3_blob_write()

---

Обработчик соединения с базой данных

typedef struct sqlite3 sqlite3;

Каждая открытая база данных SQLite представляется указателем на экземпляр непрозрачной структуры, названной "sqlite3". Полезно думать об указателе sqlite3 как об объекте. sqlite3_open(), sqlite3_open16() и sqlite3_open_v2() его конструкторы, а sqlite3_close() и sqlite3_close_v2() деструкторы. Есть много других интерфейсов (таких как sqlite3_prepare_v2(), sqlite3_create_function() и sqlite3_busy_timeout(), которые являются методами на объекте sqlite3.

3 конструктора, использующих этот объект: sqlite3_open(), sqlite3_open16() и sqlite3_open_v2()

2 деструктора, использующих этот объект: sqlite3_close() и sqlite3_close_v2()

79 методов используют этот объект:

• sqlite3_autovacuum_pages
• sqlite3_blob_open
• sqlite3_busy_handler
• sqlite3_busy_timeout
• sqlite3_changes
• sqlite3_changes64
• sqlite3_collation_needed
• sqlite3_collation_needed16
• sqlite3_commit_hook
• sqlite3_create_collation
• sqlite3_create_collation16
• sqlite3_create_collation_v2
• sqlite3_create_function
• sqlite3_create_function16
• sqlite3_create_function_v2
• sqlite3_create_module
• sqlite3_create_module_v2
• sqlite3_create_window_function
• sqlite3_db_cacheflush
• sqlite3_db_config
• sqlite3_db_filename
• sqlite3_db_mutex
• sqlite3_db_name
• sqlite3_db_readonly
• sqlite3_db_release_memory
• sqlite3_db_status
• sqlite3_drop_modules
• sqlite3_enable_load_extension
• sqlite3_errcode
• sqlite3_errmsg
• sqlite3_errmsg16
• sqlite3_error_offset
• sqlite3_errstr
• sqlite3_exec
• sqlite3_extended_errcode
• sqlite3_extended_result_codes
• sqlite3_file_control
• sqlite3_free_table
• sqlite3_get_autocommit
• sqlite3_get_clientdata
• sqlite3_get_table
• sqlite3_interrupt
• sqlite3_is_interrupted
• sqlite3_last_insert_rowid
• sqlite3_limit
• sqlite3_load_extension
• sqlite3_next_stmt
• sqlite3_overload_function
• sqlite3_prepare
• sqlite3_prepare16
• sqlite3_prepare16_v2
• sqlite3_prepare16_v3
• sqlite3_prepare_v2
• sqlite3_prepare_v3
• sqlite3_preupdate_blobwrite
• sqlite3_preupdate_count
• sqlite3_preupdate_depth
• sqlite3_preupdate_hook
• sqlite3_preupdate_new
• sqlite3_preupdate_old
• sqlite3_profile
• sqlite3_progress_handler
• sqlite3_rollback_hook
• sqlite3_set_authorizer
• sqlite3_set_clientdata
• sqlite3_set_last_insert_rowid
• sqlite3_system_errno
• sqlite3_table_column_metadata
• sqlite3_total_changes
• sqlite3_total_changes64
• sqlite3_trace
• sqlite3_trace_v2
• sqlite3_txn_state
• sqlite3_unlock_notify
• sqlite3_update_hook
• sqlite3_wal_autocheckpoint
• sqlite3_wal_checkpoint
• sqlite3_wal_checkpoint_v2
• sqlite3_wal_hook

---

Динамический объект последовательности

typedef struct sqlite3_str sqlite3_str;

Экземпляр объекта sqlite3_str содержит динамично измеренную последовательность в процессе создания.

Жизненный цикл объекта sqlite3_str следующий:

1. Объект sqlite3_str создается, используя sqlite3_str_new().
2. Текст добавлен к объекту sqlite3_str, используя различные методы, такие как sqlite3_str_appendf().
3. Объект sqlite3_str разрушен, и последовательность, которую он создал, возвращена, используя sqlite3_str_finish().

1 конструктор, использующий этот объект: sqlite3_str_new()

1 деструктор, использующий этот объект: sqlite3_str_finish()

9 методов используют этот объект:

• sqlite3_str_append
• sqlite3_str_appendall
• sqlite3_str_appendchar
• sqlite3_str_appendf
• sqlite3_str_errcode
• sqlite3_str_length
• sqlite3_str_reset
• sqlite3_str_value
• sqlite3_str_vappendf

---

Определенный приложением кэш страницы

typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
struct sqlite3_pcache_methods2 {
  int iVersion;
  void *pArg;
  int (*xInit)(void*);
  void (*xShutdown)(void*);
  sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  int (*xPagecount)(sqlite3_pcache*);
  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
       unsigned oldKey, unsigned newKey);
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  void (*xDestroy)(sqlite3_pcache*);
  void (*xShrink)(sqlite3_pcache*);
};

sqlite3_config( SQLITE_CONFIG_PCACHE2, ...) может зарегистрировать альтернативное внедрение кэша страницы, передав в копию структуры sqlite3_pcache_methods2. Во многих запросах большая часть памяти кучи, ассигнованной SQLite, используется для кэша страницы. Осуществляя свой кэш страницы, используя этот API, приложение может лучше управлять объемом памяти, потребляемым SQLite, путем определения, как память ассигнована и освобождена и политикой, определяющей точно, какие части файла базы данных и как долго кэшировать.

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

Содержание структуры sqlite3_pcache_methods2 копируется к внутреннему буферу SQLite в рамках вызова sqlite3_config. Следовательно применение может отказаться от параметра после вызова sqlite3_config().

Метод xInit() вызывают однажды для каждого эффективного запроса sqlite3_initialize() (обычно только однажды в течение целой жизни процесса). Метод xInit() передает копию значения sqlite3_pcache_methods2.pArg. Цель метода xInit() состоит в том, чтобы настроить глобальные структуры данных, требуемые внедрением кэша страницы. Если xInit() = NULL, то встроенный кэш страницы по умолчанию используется вместо определенного кэша страницы.

Метод xShutdown() вызван sqlite3_shutdown(). Это может использоваться, чтобы очистить любые ресурсы перед закрытием процесса при необходимости. Метод xShutdown() может быть NULL.

SQLite автоматически преобразовывает в последовательную форму вызовы xInit, так что xInit не должен быть ориентирован на многопоточное исполнение. Метод xShutdown вызывают только из sqlite3_shutdown() таким образом, это не должно быть ориентировано на многопоточное исполнение. Все другие методы должны быть ориентированы на многопоточное исполнение в многопоточных средах.

SQLite никогда не будет вызывать xInit() несколько раз без прошедшего xShutdown().

SQLite вызывает xCreate(), чтобы построить новый экземпляр кэша. SQLite будет, как правило, создавать один экземпляр кэша для каждого открытого файла базы данных, хотя это не гарантируется. Первый параметр, szPage, является размером в байтах страниц, которые должны быть ассигнованы кэшом. szPage всегда будет степенью 2. Второй параметр szExtra это число байт дополнительного хранения, связанного с каждой записью кэша страницы. szExtra параметр будет число меньше 250. SQLite будет использовать дополнительные szExtra байты на каждой странице, чтобы сохранить метаданные об основной странице базы данных на диске. Значение, переданное в szExtra, зависит от версии SQLite, целевой платформы и того, как SQLite был собран. Третий аргумент xCreate(), bPurgeable, будет true, если создаваемый кэш создан для страниц базы данных файла, хранимого на диске или false, если это будет использоваться для базы данных в памяти. Внедрение кэша не должно делать что-либо специальное со значением bPurgeable, это чисто консультативное. На кэше, где bPurgeable = false, SQLite никогда не будет вызывать xUnpin() кроме сознательного удаления страницы. Другими словами, xUnpin() на кэше с bPurgeable = false будут всегда устанавливать флаг в true. Следовательно, кэш, созданный с bPurgeable = false, никогда не будет содержать неприкрепленных страниц.

Метод xCachesize() SQLite может вызвать в любое время, чтобы установить предложенный максимальный размер кэша (число сохраненных страниц) экземпляра кэша, переданного как первый аргумент. Это формируемое использование значением SQLite "PRAGMA cache_size". Как с bPurgeable, не требуется делать что-либо с этим значением, это только консультативное.

Метод xPagecount() должен возвратить число страниц, в настоящее время хранимых в кэше, вместе прикрепленных и неприкрепленных.

Метод xFetch() определяет местонахождение страницы в кэше и возвращает указатель на объект sqlite3_pcache_page, связанный с той страницей или NULL. Элемент pBuf возвращенного объекта sqlite3_pcache_page будет указателем на буфер szPage байтов, используемых, чтобы сохранить содержание страницы единой базы данных. Элемент pExtra sqlite3_pcache_page будет указателем на szExtra байты дополнительного хранения, которое SQLite просил для каждой записи в кэше страницы.

Страница, которая будет получена, определяется ключом. Минимальное значение ключа равняется 1. После того, как это было получено, используя xFetch, страница считается "прикрепленной".

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

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

SQLite будет обычно вызывать xFetch() с createFlag = 0 или 1. SQLite будет использовать createFlag = 2 только после предшествующего вызова с createFlag = 1. При промежуточных вызовах xFetch() SQLite может попытаться не прикреплять одну или более страниц кэша, сбросив содержание прикрепленных страниц на диск и синхронизируя дисковый кэш операционной системы.

xUnpin() вызван SQLite с указателем на в настоящее время прикрепляемую страницу как ее второй аргумент. Если третий параметр discard не 0, то страница должна быть выселена из кэша. Если параметр discard = 0, то от страницы можно отказаться или сохранить на усмотрение внедрения кэша страницы. Внедрение кэша страницы может выселить неприкрепленные страницы в любое время.

Кэш не должен выполнять подсчет ссылок. Единственный запрос к xUnpin() не прикрепляет страницу независимо от количества предшествующих вызовов xFetch().

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

Когда SQLite вызывает xTruncate(), кэш должен отказаться от всех существующих записей кэша с номерами страниц (ключами) больше или равных iLimit, переданному xTruncate(). Если какая-либо из этих страниц прикреплена, они неявно не прикреплены, означая, что от них можно безопасно отказаться.

xDestroy() используется, чтобы удалить кэш, ассигнованный xCreate(). Должны быть освобождены все ресурсы, связанные с указанным кэшом. После запроса xDestroy() SQLite рассматривает обработчик sqlite3_pcache* как нгеправильный и не будет использовать его ни с какими другими функциями sqlite3_pcache_methods2.

SQLite вызывает xShrink(), когда это хочет освободить из кэша страницы как можно больше памяти кучи. Внедрение кэша страницы не обязано освободить память, но внедрения хорошего поведения должны приложить все усилия.

---

Подготовленный объект запроса

typedef struct sqlite3_stmt sqlite3_stmt;

Экземпляр этого объекта представляет единственный SQL-оператор, который был собран в двоичную форму и готов быть оцененным.

Думайте о каждом SQL-операторе как о программе. Оригинальный код на SQL ее исходный код. Подготовленный объект запроса это собранный объектный код. Весь SQL должен быть преобразован в подготовленный запрос, прежде чем им можно будет управлять.

Жизненный цикл подготовленного объекта запроса обычно идет так:

1. Создайте подготовленный объект запроса, используя sqlite3_prepare_v2().
2. Свяжите значения с параметрами через sqlite3_bind_*().
3. Управляйте SQL, вызывая sqlite3_step() один или несколько раз.
4. Перезагрузите подготовленный запрос, используя sqlite3_reset(), затем вернитесь к шагу 2. Сделайте это ноль или больше раз.
5. Разрушьте объект, используя sqlite3_finalize().

6 конструкторов, использующих этот объект:

• sqlite3_prepare
• sqlite3_prepare16
• sqlite3_prepare16_v2
• sqlite3_prepare16_v3
• sqlite3_prepare_v2
• sqlite3_prepare_v3

1 деструктор, использующий этот объект: sqlite3_finalize()

53 метода используют этот объект:

• sqlite3_bind_blob
• sqlite3_bind_blob64
• sqlite3_bind_double
• sqlite3_bind_int
• sqlite3_bind_int64
• sqlite3_bind_null
• sqlite3_bind_parameter_count
• sqlite3_bind_parameter_index
• sqlite3_bind_parameter_name
• sqlite3_bind_pointer
• sqlite3_bind_text
• sqlite3_bind_text16
• sqlite3_bind_text64
• sqlite3_bind_value
• sqlite3_bind_zeroblob
• sqlite3_bind_zeroblob64
• sqlite3_clear_bindings
• sqlite3_column_blob
• sqlite3_column_bytes
• sqlite3_column_bytes16
• sqlite3_column_count
• sqlite3_column_database_name
• sqlite3_column_database_name16
• sqlite3_column_decltype
• sqlite3_column_decltype16
• sqlite3_column_double
• sqlite3_column_int
• sqlite3_column_int64
• sqlite3_column_name
• sqlite3_column_name16
• sqlite3_column_origin_name
• sqlite3_column_origin_name16
• sqlite3_column_table_name
• sqlite3_column_table_name16
• sqlite3_column_text
• sqlite3_column_text16
• sqlite3_column_type
• sqlite3_column_value
• sqlite3_data_count
• sqlite3_db_handle
• sqlite3_expanded_sql
• sqlite3_normalized_sql
• sqlite3_reset
• sqlite3_sql
• sqlite3_step
• sqlite3_stmt_busy
• sqlite3_stmt_explain
• sqlite3_stmt_isexplain
• sqlite3_stmt_readonly
• sqlite3_stmt_scanstatus
• sqlite3_stmt_scanstatus_reset
• sqlite3_stmt_scanstatus_v2
• sqlite3_stmt_status

---

Объект значения с динамическим контролем типов

typedef struct sqlite3_value sqlite3_value;

SQLite использует объект sqlite3_value, чтобы представлять все значения, которые могут быть сохранены в таблице базы данных. SQLite использует динамический контроль типов для значений, которые это хранит. Значения, сохраненные в объектах sqlite3_value, могут быть целыми числами, значениями с плавающей точкой, последовательностями, BLOB или NULL.

Объект sqlite3_value может быть "protected" или "unprotected". Некоторые интерфейсы требуют защищенного sqlite3_value. Другие интерфейсы примут защищенный или незащищенный sqlite3_value. Каждый интерфейс, который принимает аргументы sqlite3_value, определяет, требует ли он защищенного sqlite3_value. sqlite3_value_dup() может использоваться, чтобы построить новый защищенный sqlite3_value из незащищенного sqlite3_value.

Термины "protected" и "unprotected" относятся к тому, проводится ли mutex. Внутренний mutex проводится для защищенного объекта sqlite3_value, но никакой mutex не проводится для незащищенного объекта sqlite3_value. Если SQLite собран, чтобы быть однопоточным (с SQLITE_THREADSAFE=0, sqlite3_threadsafe() вернет 0) или если SQLite управляют в одном из уменьшенных mutex режимов SQLITE_CONFIG_SINGLETHREAD или SQLITE_CONFIG_MULTITHREAD, тогда нет никакого различия между защищенными и незащищенными объектами sqlite3_value, и они могут использоваться попеременно. Однако для максимальной переносимости кода рекомендуется, чтобы запросы все еще делали различие между защищенными и незащищенными объектами sqlite3_value, даже когда это не строго необходимо.

Объекты sqlite3_value, которые передаются как параметры во внедрение определяемых функций SQL, защищены. Объекты sqlite3_value, возвращенные sqlite3_vtab_rhs_value(), защищены. Объекты sqlite3_value, возвращенные sqlite3_column_value(), незащищены. Незащищенные объекты sqlite3_value могут использоваться только в качестве аргументов sqlite3_result_value(), sqlite3_bind_value() и sqlite3_value_dup(). sqlite3_value_type() требуют защищенных объектов sqlite3_value.

19 методов используют этот объект:

• sqlite3_value_blob
• sqlite3_value_bytes
• sqlite3_value_bytes16
• sqlite3_value_double
• sqlite3_value_dup
• sqlite3_value_encoding
• sqlite3_value_free
• sqlite3_value_frombind
• sqlite3_value_int
• sqlite3_value_int64
• sqlite3_value_nochange
• sqlite3_value_numeric_type
• sqlite3_value_pointer
• sqlite3_value_subtype
• sqlite3_value_text
• sqlite3_value_text16
• sqlite3_value_text16be
• sqlite3_value_text16le
• sqlite3_value_type

---

Устаревшие функции

#ifndef SQLITE_OMIT_DEPRECATED
int sqlite3_aggregate_count(sqlite3_context*);
int sqlite3_expired(sqlite3_stmt*);
int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
int sqlite3_global_recover(void);
void sqlite3_thread_cleanup(void);
int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
                         void*,sqlite3_int64);
#endif

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

---

Online Backup API

sqlite3_backup *sqlite3_backup_init(
  sqlite3 *pDest,                        /* Destination database handle */
  const char *zDestName,                 /* Destination database name */
  sqlite3 *pSource,                      /* Source database handle */
  const char *zSourceName                /* Source database name */
);
int sqlite3_backup_step(sqlite3_backup *p, int nPage);
int sqlite3_backup_finish(sqlite3_backup *p);
int sqlite3_backup_remaining(sqlite3_backup *p);
int sqlite3_backup_pagecount(sqlite3_backup *p);

Резервный API копирует содержание одной базы данных в другую. Это полезно для создания резервных копий баз данных или для копирования баз данных в памяти к или от постоянных файлов.

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

Выполнить операцию резервного копирования:

1. sqlite3_backup_init() вызывают однажды, чтобы инициализировать резервную копию,
2. sqlite3_backup_step() вызывают один или несколько раз, чтобы передать данные между этими двумя базами данных и наконец
3. sqlite3_backup_finish() вызывают, чтобы высвободить все ресурсы, связанные с операцией резервного копирования.

Должен быть точно один запрос sqlite3_backup_finish() для каждого успешного вызова sqlite3_backup_init().

sqlite3_backup_init()

Параметры D и N для sqlite3_backup_init(D,N,S,M) это соединения с базой данных, связанные с целевой базой данных и именем базы данных, соответственно. Имя базы данных "main" для главной базы данных, "temp" для временной базы данных или имени, определенного после ключевого слова AS в ATTACH для добавленной базы данных. Аргументы S и M, переданные sqlite3_backup_init(D,N,S,M), определяют соединение с базой данных и имя базы данных исходной базы данных, соответственно. Источник и целевая база данных (параметры S и D) должны отличаться, иначе sqlite3_backup_init(D,N,S,M) потерпит неудачу с ошибкой.

Вызов sqlite3_backup_init() потерпит неудачу, возвращая NULL, если уже будет транзакция чтения или чтения-записи, открытая на целевой базе данных.

Если ошибка происходит в sqlite3_backup_init(D,N,S,M), NULL вернется, код ошибки и сообщение об ошибке сохранены в связи целевой базы данных D. Код ошибки и сообщение для неудавшегося вызова sqlite3_backup_init() можно получить через sqlite3_errcode(), sqlite3_errmsg() и/или sqlite3_errmsg16(). Успешный вызов sqlite3_backup_init() возвращает указатель на объект sqlite3_backup. Объект sqlite3_backup может использоваться с sqlite3_backup_step() и sqlite3_backup_finish(), чтобы выполнить указанную операцию резервного копирования.

sqlite3_backup_step()

Функция sqlite3_backup_step(B,N) скопирует до N страниц между источником и целевой базой данных, определенных объектом sqlite3_backup B. Если N отрицателен, все остающиеся исходные страницы копируются. Если sqlite3_backup_step(B,N) успешно копирует N страниц и есть еще больше страниц, которые будут скопированы, то функция возвращает SQLITE_OK. Если sqlite3_backup_step(B,N) успешно заканчивает копировать все страницы от источника до места назначения, то это возвращает SQLITE_DONE. Если ошибка происходит, выполняя sqlite3_backup_step(B,N), код ошибки возвращен. А также SQLITE_OK и SQLITE_DONE, вызывая sqlite3_backup_step(), могут вернуть расширенный код ошибки SQLITE_READONLY, SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED или SQLITE_IOERR_XXX.

sqlite3_backup_step() может вернуть SQLITE_READONLY если:

1. целевая база данных была открыта только для чтения,
2. целевая база данных использует журнал с упреждающей записью и размеры страниц в исходной и результирующей БД отличаются,
3. целевая база данных это база данных в памяти и размеры страниц в исходной и результирующей БД отличаются.

Если sqlite3_backup_step() не может получить необходимую блокировку файловой системы, то занятая функция-обработчик вызвана (если вы ее определяете). Если занятый обработчик возвращает отличное от 0 значение, прежде чем блокировка будет доступна, то вызывающий получит SQLITE_BUSY. В этом случае запрос sqlite3_backup_step() может быть повторен позже. Если исходное соединение с базой данных используется, чтобы писать исходную базу данных, когда sqlite3_backup_step() вызван, SQLITE_LOCKED немедленно возвращен. Снова, в этом случае запрос sqlite3_backup_step() может быть повторен позже. Если возвращено SQLITE_IOERR_XXX, SQLITE_NOMEM, SQLITE_READONLY, то нет никакого смысла в повторении sqlite3_backup_step(). Эти ошибки считают фатальными. Применение должно признать, что операция резервного копирования не удалась и передает обработчик операции резервного копирования sqlite3_backup_finish(), чтобы высвободить связанные ресурсы.

Первый вызов sqlite3_backup_step() получает монопольную блокировку на файле назначения. Монопольная блокировка не снята до любого вызова sqlite3_backup_finish() или завершения операции резервного копирования (sqlite3_backup_step() вернул SQLITE_DONE). Каждый запрос sqlite3_backup_step() получает коллективную блокировку на исходной базе данных, которая продолжается в период запроса sqlite3_backup_step(). Поскольку исходная база данных не блокирована между вызовами sqlite3_backup_step(), она может быть изменена на полпути процесса резервного копирования. Если исходная база данных будет изменена внешним процессом или через соединение с базой данных кроме того, используемого операцией резервного копирования, то резервная копия будет автоматически перезапущена следующим запросом sqlite3_backup_step(). Если исходная база данных изменяется с использованием того же самого соединения с базой данных, которое используется операцией резервного копирования, то резервная база данных автоматически обновляется в то же время.

sqlite3_backup_finish()

Когда sqlite3_backup_step() вернет SQLITE_DONE приложение хочет остановить операцию резервного копирования, приложение должно разрушить sqlite3_backup передав его sqlite3_backup_finish(). Интерфейс sqlite3_backup_finish() высвобождает все ресурсы, связанные с объектом sqlite3_backup. Если sqlite3_backup_step() еще не возвратил SQLITE_DONE, любая активная транзакция записи на целевой базе данных отменена. Объект sqlite3_backup некорректен и не может использоваться после sqlite3_backup_finish().

Значение, возвращенное sqlite3_backup_finish, это SQLITE_OK если ошибки произошли, независимо от того, закончил ли sqlite3_backup_step(). Если сбой памяти или ошибка IO произошли во время какого-либо предшествующего sqlite3_backup_step(), обращаясь к тому же самому объекту sqlite3_backup, то sqlite3_backup_finish() возвращает соответствующий код ошибки.

Возврат SQLITE_BUSY или SQLITE_LOCKED из sqlite3_backup_step() не является систематической ошибкой и не затрагивает возвращаемое значение sqlite3_backup_finish().

sqlite3_backup_remaining() и sqlite3_backup_pagecount()

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

Параллельное использование обработчиков базы данных

Исходное соединение с базой данных может использоваться на другие цели, в то время как операция резервного копирования идет полным ходом. Если SQLite собирается и формируется, чтобы поддержать ориентированные на многопоточное исполнение соединения с базой данных, то исходное соединение с базой данных может использоваться одновременно из других потоков.

Однако, приложение должно гарантировать, что связь целевой базы данных не передается ни к какому другому API (любым потоком) после того, как вызван sqlite3_backup_init() и перед соответствующим запросом sqlite3_backup_finish(). SQLite в настоящее время не проверяет, получает ли приложение неправильно доступ к к связи целевой базы данных и таким образом, ни о каком коде ошибки не сообщают, но операции могут работать со сбоями, тем не менее. Использование связи целевой базы данных, в то время как резервная копия происходит, могло бы также вызвать мертвую блокировку mutex.

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

Объект sqlite3_backup частично ориентирован на многопоточное исполнение. Многократные потока могут безопасно сделать многократные параллельные вызовы sqlite3_backup_step(). Однако, sqlite3_backup_remaining() и sqlite3_backup_pagecount() API не строго ориентированы на многопоточное исполнение. Если они вызваны в то же время, что и другой поток вызвал sqlite3_backup_step(), возможно, что они возвращают недействительные значения.

---

Подсчитайте количество измененных строк

int sqlite3_changes(sqlite3*);
sqlite3_int64 sqlite3_changes64(sqlite3*);

Эти функции возвращают количество измененных, вставленных или удаленных строк последним INSERT, UPDATE или DELETE на соединении с базой данных, определенном единственным параметром. Две функции идентичны за исключением типа возвращаемого значения, смотря по количеству строк. Если оно больше, чем максимальное значение, поддержанное типом "int", то возвращаемое значение sqlite3_changes() не определено. Выполнение любого другого типа SQL-оператора не изменяет значение, возвращенное этими функциями.

Только изменения, внесенные непосредственно INSERT, UPDATE или DELETE, рассматриваются, вспомогательные изменения, вызванные триггерами, действиями внешнего ключа или ограничительной резолюцией REPLACE, не посчитаны.

Изменения представления, которые перехвачены INSTEAD OF triggers, не посчитаны. Значение, возвращенное returned by sqlite3_changes() сразу после INSERT, UPDATE или DELETE, которым управляют согласно представлению, всегда является нолем. Только изменения, внесенные в реальные таблицы, посчитаны.

Вещи более сложны, если выполняется sqlite3_changes() в то время, как работает триггер. Это может произойти, если программа использует SQL-функцию changes() или если некоторая другая функция обратного вызова вызывает непосредственно sqlite3_changes():

• Прежде, чем войти в триггер, значение, возвращенное sqlite3_changes(), сохранено. После того, как триггер отработает, исходное значение восстановлено.

• В рамках триггера каждый INSERT, UPDATE и DELETE устанавливают значение, возвращенное sqlite3_changes() после завершения как нормальное. Конечно, это значение не будет включать изменений, выполненных подпрограммами, значение будет сохранено и восстановлено после того, как каждый подтриггер отработал.

Это означает, что, если функция SQL changes() (или подобная) используется первым INSERT, UPDATE или DELETE в триггере, это возвращает значение, как установлено, когда запроса начал выполняться. Если это используется вторым или последующим таким запросом в рамках триггера, возвращенное значение отражает количество строк, измененных предыдущим INSERT, UPDATE или DELETE в том же самом триггере.

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

См. также:

• sqlite3_total_changes()
• count_changes pragma
• SQL-функция changes()
• data_version pragma

---

Закрытие соединения с базой данных

int sqlite3_close(sqlite3*);
int sqlite3_close_v2(sqlite3*);

sqlite3_close() и sqlite3_close_v2() это деструкторы для объекта sqlite3. Вызов sqlite3_close() и sqlite3_close_v2() вернут SQLITE_OK, если объект sqlite3 успешно разрушен, и освобождены все связанные ресурсы.

Идеально, запросы должны завершить все связанные объекты подготовленных запросов, закрыть все обработчики BLOB и закрыть все объекты sqlite3_backup, связанные с объектом sqlite3 до попытки закрыть объект. Если соединение с базой данных связано с незавершенными подготовленными запросами, обработчиками BLOB и/или незаконченными объектами sqlite3_backup, sqlite3_close() оставит соединение с базой данных открытым и возвратит SQLITE_BUSY. Если sqlite3_close_v2() с незавершенными подготовленными запросами, обработчиками BLOB и/или незаконченным sqlite3_backups, это вернет SQLITE_OK, независимо, но вместо того, чтобы немедленно освободить соединение с базой данных, он отмечает соединение с базой данных как непригодное "zombie" и принимает меры, чтобы автоматически освободить соединение с базой данных после того, как все подготовленные запросы завершены, все обработчики BLOB закрываются и все резервные копии закончились. sqlite3_close_v2() предназначается для использования с базовыми языками, где порядок, в котором вызывают деструкторы, произволен.

Если объект sqlite3 разрушен, в то время как транзакция открыта, транзакция автоматически отменена.

C-параметр sqlite3_close(C) и sqlite3_close_v2(C) должен быть NULL или указателем объекта sqlite3, полученным из sqlite3_open(), sqlite3_open16() или sqlite3_open_v2(), и не закрыт ранее. Запрос sqlite3_close() или sqlite3_close_v2() с NULL не делает ничего.

---

Сопоставление необходимых отзывов

int sqlite3_collation_needed(sqlite3*, void*,
                             void(*)(void*,sqlite3*,int eTextRep,
                             const char*));
int sqlite3_collation_needed16(sqlite3*, void*, void(*)(void*,sqlite3*,
                               int eTextRep,const void*));

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

Если функция зарегистрирована, используя sqlite3_collation_needed(), то ей передаются названия неопределенных сортирующих последовательностей как последовательности, закодированные в UTF-8. Если использована sqlite3_collation_needed16(), имена передаются как UTF-16 в машинном порядке байтов хоста. Запрос к любой функции заменяет существующий отзыв.

Когда отзыв вызван, первым переданным аргументом является копия второго аргумента sqlite3_collation_needed() или sqlite3_collation_needed16(). Второй аргумент это соединение с базой данных. Третий аргумент один из SQLITE_UTF8, SQLITE_UTF16BE или SQLITE_UTF16LE, указывая на самую желательную форму требуемой функции сортирующей последовательности. Четвертый параметр задает название необходимой сортирующей последовательности.

Функция обратного вызова должна зарегистрировать желаемое сопоставление, используя sqlite3_create_collation(), sqlite3_create_collation16() или sqlite3_create_collation_v2().

---

Источник данных в результате запроса

const char *sqlite3_column_database_name(sqlite3_stmt*,int);
const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
const char *sqlite3_column_table_name(sqlite3_stmt*,int);
const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);

Эта хранимая процедура обеспечивает средство определить базу данных, таблицу и столбец таблицы, который является происхождением конкретного столбца результата в SELECT. Название базы данных, таблицы или колонки может быть возвращено как UTF-8 или как последовательность UTF-16. _database_ возвращает имя базы данных, _table_ возвращает имя таблицы и origin_ возвращает имя столбца. Возвращаемая строка действительна, пока подготовленный запрос не уничтожен, используя sqlite3_finalize() или пока запрос автоматически не подготовлен повторно первым запросом sqlite3_step() для конкретного выполнения или пока та же самая информация не запрошена снова в ином кодировании.

Возвращенные имена являются оригинальными названиями базы данных, таблицы и колонки.

Первый аргумент это подготовленный запрос. Эти функции возвращают информацию об N-м столбце результата, возвращенном запросом, где N это второй аргумент функции. Крайний левый столбец это колонка 0.

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

Как со всеми другими API SQLite, конец имен которых "16", возвращают строку в UTF-16, другие функции, возвращают UTF-8.

Это API доступно только, если библиотека была собрана с символом C-препроцессора SQLITE_ENABLE_COLUMN_METADATA.

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

---

Объявленный тип данных результата запроса

const char *sqlite3_column_decltype(sqlite3_stmt*,int);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

Первый параметр это подготовленный запрос. Если это SELECT N-й столбец возвращенного набора результатов этого SELECT это столбец таблицы (не выражение или подзапрос) тогда, заявленный тип столбца таблицы возвращен. Если N-й столбец набора результатов это выражение или подзапрос, то вернется NULL. Возвращаемая строка всегда в UTF-8.

Например, учитывая схему базы данных:

CREATE TABLE t1(c1 VARIANT);

следующий запрос будет собран:

SELECT c1 + 1, c1 FROM t1;

Это возвратило бы последовательность "VARIANT" для второго столбца результата (i==1) и NULL для первого столбца результата (i==0).

SQLite использует динамический тип во время выполнения. Таким образом, просто, потому что колонка, как объявляют, содержит конкретный тип, не означает, что данные в той колонке, имеют заявленный тип. SQLite со строгим контролем типов, но типы динамические. Тип связан с отдельными значениями, не с контейнерами, используемыми, чтобы хранить те значения.

---

Имена столбцов в наборе результатов

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

Эта хранимая процедура возвращает имя, назначенное на конкретную колонку в наборе результатов SELECT. sqlite3_column_name() возвращает указатель на законченную нолем последовательность UTF-8, и sqlite3_column_name16() возвращает указатель на законченную нолем последовательность UTF-16. Первый параметр это подготовленный запрос, который осуществляет SELECT. Второй параметр задает номер столбца. Крайний левый столбец 0.

Указатель возвращаемой строки действителен для любого подготовленного запроса до его разрушения sqlite3_finalize() или пока запрос автоматически не переподготовлен первым запросом sqlite3_step() для конкретного выполнения или до следующего sqlite3_column_name() или sqlite3_column_name16() на той же самой колонке.

Если sqlite3_malloc() терпит неудачу во время обработки любой функции (например, во время преобразования от UTF-8 в UTF-16), тогда возвращен NULL.

Название столбца результата это значение пункта "AS" для той колонки, если есть пункт AS. Если нет никакого пункта AS, тогда название колонки не указано и может измениться от одного выпуска SQLite к следующему.

---

Отзывы уведомления о коммите и об обратной перемотке

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

sqlite3_commit_hook() регистрирует функцию обратного вызова, которая будет вызвана каждый раз, когда транзакция коммитится. Любой отзыв, установленный предыдущим запросом sqlite3_commit_hook(), для того же самого соединения с базой данных, отвергнут. sqlite3_rollback_hook() регистрирует функцию обратного вызова, которая будет вызвана каждый раз, когда транзакция отменена. Любой отзыв, установленный предыдущим запросом sqlite3_rollback_hook(), для того же самого соединения с базой данных, отвергнут. Через аргумент pArg проходят к отзыву. Если отзыв функции перехвата коммита возвращает отличное от нуля значение, то передача преобразовывается в обратную перемотку.

Функции sqlite3_commit_hook(D,C,P) и sqlite3_rollback_hook(D,C,P) возвращают аргумент P от предыдущего вызова той же самой функции на том же самом соединении с базой данных D или NULL для первого вызова каждой функции на D.

Внедрение отзыва не должно делать ничего, что изменит соединение с базой данных, которое вызвало отзыв. Любые действия, чтобы изменить соединение с базой данных должны быть отсрочены до окончания завершения sqlite3_step(). Обратите внимание на то, что управление любыми другими SQL-операторами, включая операторы SELECT, или просто запрос sqlite3_prepare_v2() и sqlite3_step() изменят соединения с базой данных.

Регистрация функции NULL отключает отзыв.

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

В целях этого API транзакция, как говорят, была отменена, если явный запрос "ROLLBACK" выполняется, или ошибка или ограничение заставляют происходить неявную обратную перемотку. Отзыв обратной перемотки не вызван, если транзакция автоматически отменена, потому что соединение с базой данных закрывается.

---

Диагностика параметров компиляции библиотеки времени выполнения

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
int sqlite3_compileoption_used(const char *zOptName);
const char *sqlite3_compileoption_get(int N);
#else
# define sqlite3_compileoption_used(X) 0
# define sqlite3_compileoption_get(X)  ((void*)0)
#endif

sqlite3_compileoption_used() вернет 0 или 1 указывая, был ли указанный выбор определен во время компиляции. Префикс SQLITE_ может быть опущен в имени выбора, переданного sqlite3_compileoption_used().

sqlite3_compileoption_get() позволяет повторять по списку вариантов, которые были определены во время компиляции, возвратив N-ю последовательность выбора времени компиляции. Если N вне диапазона, sqlite3_compileoption_get() вернет NULL. Префикс SQLITE_ опущен в любых последовательностей, возвращенных sqlite3_compileoption_get().

Поддержка диагностических функций sqlite3_compileoption_used() и sqlite3_compileoption_get() может быть опущена, определив выбор SQLITE_OMIT_COMPILEOPTION_DIAGS во время компиляции.

---

Определите, полон ли SQL-оператор

int sqlite3_complete(const char *sql);
int sqlite3_complete16(const void *sql);

Это полезно во время ввода командной строки, чтобы определить, формирует ли в настоящее время введенный текст полный SQL-оператор или дополнительный ввод необходим прежде, чем послать текст в SQLite для парсинга. Эта хранимая процедура возвращает 1, если входная строка это полный SQL-оператор. Запрос оценивается как полный, если он заканчивается символом точки с запятой и не является префиксом правильно построенного запроса CREATE TRIGGER. Точки с запятой, которые включены в строковых литералах или именах идентификатора в кавычках или комментариях, являются зависимыми символами (они часть символа, в который они включены), и таким образом не считаются терминатором запроса. Пробелы и комментарии, которые следуют за заключительной точкой с запятой, проигнорированы.

Это возвращается 0, если запрос неполный. Если выделение памяти терпит неудачу, то SQLITE_NOMEM возвращен.

Это не разбирает SQL-операторы, таким образом не обнаружит синтаксически неправильный SQL.

Если SQLite не был инициализирован, используя sqlite3_initialize() до вызова sqlite3_complete16(), sqlite3_initialize() вызван автоматически sqlite3_complete16(). Если та инициализация потерпит неудачу, то возвращаемое значение sqlite3_complete16() не 0 независимо от того, полон ли ввод SQL.

Ввод sqlite3_complete() должен быть законченной нолем последовательностью UTF-8.

Ввод sqlite3_complete16() должен быть законченной нолем последовательностью UTF-16 в родном порядке байтов.

---

Определите новые последовательности сопоставления

int sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep,
                             void *pArg, int(*xCompare)(void*,int,
                             const void*,int,const void*));
int sqlite3_create_collation_v2(sqlite3*, const char *zName, int eTextRep,
                                void *pArg, int(*xCompare)(void*,int,
                                const void*,int,const void*),
                                void(*xDestroy)(void*));
int sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep,
                               void *pArg, int(*xCompare)(void*,int,
                               const void*,int,const void*));

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

Название сопоставления это последовательность UTF-8 для sqlite3_create_collation() и sqlite3_create_collation_v2() или строка UTF-16 в родном порядке байтов для sqlite3_create_collation16(). Имена сопоставления, которые выдерживают сравнение равных, согласно sqlite3_strnicmp(), считаются тем же самым именем.

Третьим аргументом (eTextRep) должна быть одна из констант:

• SQLITE_UTF8,
• SQLITE_UTF16LE,
• SQLITE_UTF16BE,
• SQLITE_UTF16 или
• SQLITE_UTF16_ALIGNED.

eTextRep определяет кодирование последовательностей, переданных отзыву функции сопоставления xCompare. SQLITE_UTF16 и SQLITE_UTF16_ALIGNED для eTextRep оценивают строки в UTF16 с родным порядком байтов. SQLITE_UTF16_ALIGNED выравнивает адрес на байт.

Четвертый аргумент, pArg, является указателем данных приложения, через который передают первый аргумент отзыва функции сопоставления.

Пятым аргументом, xCompare, является указатель на функцию сопоставления. Многократные функции сопоставления могут быть зарегистрированы, используя то же самое имя, но с различными параметрами eTextRep, SQLite будет использовать функцию, которая требует наименьшего количества преобразования объема данных. Если xCompare = NULL, функция сопоставления удалена. Когда все функции сопоставления, имеющие то же самое имя, удалены, то сопоставление больше неприменимо.

Отзыв функции сопоставления вызван с копией указателя pArg данных приложения и с двумя последовательностями в кодировании, определенном eTextRep. Два параметра целого числа отзыва функции сопоставления это длина двух последовательностей в байтах. Функция сопоставления должна возвратить целое число, которое является отрицательным, нолем или положительным, если первая последовательность меньше, равна или больше, чем вторая, соответственно. Функция сопоставления должна всегда давать тот же самый ответ, при тех же вводных. Если две или больше функции сопоставления зарегистрированы к тому же самому имени сопоставления (используя различные значения eTextRep), все должны дать эквивалентный ответ, когда вызваны с эквивалентными последовательностями. Функция сопоставления должна повиноваться следующим свойствам для всех последовательностей A, B и C:

1. Если A==B, то B==A.
2. Если A==B и B==C, то A==C.
3. Если A<B, то B>A.
4. Если A<B и B<C, то A<C.

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

sqlite3_create_collation_v2() работает подобно sqlite3_create_collation() с дополнением, что отзыв xDestroy вызван на pArg, когда функция сопоставления удалена. Сопоставляющие функции удалены, когда они отвергнуты более поздними вызовами функциям создания сопоставления или когда соединение с базой данных закрывается, используя sqlite3_close().

xDestroy НЕ вызывают, если sqlite3_create_collation_v2() провалилась. Приложения, которые вызывают sqlite3_create_collation_v2() с не-NULL xDestroy, должны проверить код возврата и избавиться от указателя данных приложения сами вместо того, чтобы ожидать, что SQLite будет иметь дело с ним. Это отличается от любого интерфейса SQLite. Несоответствие неудачно, но не может быть изменено, не ломая обратную совместимость.

См. также: sqlite3_collation_needed() и sqlite3_collation_needed16().

---

Создайте и разрушьте имена файлов VFS

sqlite3_filename sqlite3_create_filename(const char *zDatabase,
                                         const char *zJournal,
                                         const char *zWal, int nParam,
                                         const char **azParam);
void sqlite3_free_filename(sqlite3_filename);

Эти интерфейсы обеспечиваются для использования внедрениями прокладки VFS и не полезны за пределами этого контекста.

sqlite3_create_filename(D,J,W,N,P) ассигнует память, чтобы держать версию имени файла базы данных D с соответствующим файлом J журнала и файлом W WAL и с парами ключа/значений N параметров URI в массиве P. Результат sqlite3_create_filename(D,J,W,N,P) это указатель на имя файла базы данных, которое безопасно передать таким функциям, как:

• sqlite3_uri_parameter(),
• sqlite3_uri_boolean(),
• sqlite3_uri_int64(),
• sqlite3_uri_key(),
• sqlite3_filename_database(),
• sqlite3_filename_journal() или
• sqlite3_filename_wal().

Если ошибка распределения памяти происходит, sqlite3_create_filename() мог бы возвратить NULL. Память, полученная из sqlite3_create_filename(X), должна быть освобождена соответствующим запросом sqlite3_free_filename(Y).

Параметр P в sqlite3_create_filename(D,J,W,N,P) должен быть множеством 2*N указателей на последовательности. Каждая пара указателей в этом множестве соответствует ключу и значению для параметра запроса. Параметр P может быть NULL, если N = 0. Ни один из 2*N указателей во множестве P не может быть NULL, ключевые указатели не должны быть пустыми строками. Ни один из параметров D, J или W в sqlite3_create_filename(D,J,W,N,P) не может быть NULL, хотя они могут быть пустыми строками.

sqlite3_free_filename(Y) освобождает выделение памяти, ранее полученное из sqlite3_create_filename(). sqlite3_free_filename(Y), где Y = NULL ничего не делает.

Если Y для sqlite3_free_filename(Y) является чем-нибудь кроме NULL или указателя, ранее полученного из sqlite3_create_filename(), то плохие вещи, такие как повреждение кучи или segfaults могут произойти. Значение Y не должна использоваться снова, после вызова sqlite3_free_filename(Y). Это означает что, если метод sqlite3_vfs.xOpen() VFS вызвали, используя Y, то соответствующий метод [sqlite3_module.xClose() должен также быть вызван до запроса sqlite3_free_filename(Y).

---

Зарегистрируйте виртуальное внедрение таблицы

int sqlite3_create_module(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData          /* Client data for xCreate/xConnect */
);
int sqlite3_create_module_v2(
  sqlite3 *db,               /* SQLite connection to register module with */
  const char *zName,         /* Name of the module */
  const sqlite3_module *p,   /* Methods for the module */
  void *pClientData,         /* Client data for xCreate/xConnect */
  void(*xDestroy)(void*)     /* Module destructor function */
);

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

Имя модуля зарегистрировано на соединении с базой данных, определенном первым параметром. Название модуля дано вторым параметром. Третий параметр это указатель на внедрение виртуального модуля таблицы. Четвертый параметр это произвольный указатель данных клиента, через который передают в xCreate и xConnect виртуального модуля таблицы, когда новая виртуальная таблица создана или повторно инициализирована.

sqlite3_create_module_v2() имеет пятый параметр, который является указателем на деструктор для pClientData. SQLite вызовет функцию деструктора (если это не будет NULL), когда SQLite больше не нужен pClientData. Деструктор будет также вызван, если запрос sqlite3_create_module_v2() потерпит неудачу. sqlite3_create_module() эквивалентен sqlite3_create_module_v2() с деструктором NULL.

Если третий параметр (указатель на объект sqlite3_module) = NULL, тогда никакой новый модуль не создается, и пропущены любые существующие модули с тем же самым именем.

См. также: sqlite3_drop_modules().

---

Коды ошибок и сообщения

int sqlite3_errcode(sqlite3 *db);
int sqlite3_extended_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
const char *sqlite3_errstr(int);
int sqlite3_error_offset(sqlite3 *db);

Если новый вызов API sqlite3_* при связи с соединением с базой данных D провалился, sqlite3_errcode(D) возвращает числовой код результата или расширенный код результата. sqlite3_extended_errcode() это то же самое за исключением того, что это всегда возвращает расширенный код результата , даже когда расширенные коды результата отключены.

Значения, возвращенные sqlite3_errcode() и/или sqlite3_extended_errcode(), могли бы измениться с каждым вызовом API. Кроме того, есть некоторые интерфейсы, которые, как гарантируют, никогда не изменят значение кода ошибки. Интерфейсы сохранения кода ошибки включают следующие:

• sqlite3_errcode()
• sqlite3_extended_errcode()
• sqlite3_errmsg()
• sqlite3_errmsg16()
• sqlite3_error_offset()

sqlite3_errmsg() и sqlite3_errmsg16() вернут текст на английском, который описывает ошибку, как UTF-8 или как UTF-16, соответственно. Памятью, чтобы хранить последовательность сообщения об ошибке управляют внутренне. Приложение не должно волноваться об освобождении результата. Однако, строка ошибки могла бы быть переписана или освобождена последующими обращениями к другим функциям интерфейса SQLite.

sqlite3_errstr() возвращает англоязычный текст, который описывает код результата, как UTF-8. Памятью, чтобы хранить последовательность сообщения об ошибке, управляют внутренне и приложение не должно ее освободить.

Если новая ошибка ссылается на определенный символ во входе SQL, SQL, sqlite3_error_offset() возвращает байтовое смещение от начала того символа. Байтовое смещение, возвращенное sqlite3_error_offset(), предполагает, что вход SQL является UTF8. Если новая ошибка не ссылается на определенный символ во входе SQL, то sqlite3_error_offset() вернет -1.

Когда преобразовано в последовательную форму многопоточный режим используется, могло бы иметь место, что вторая ошибка происходит в отдельном потоке в промежуточное время между первой ошибкой и вызовом этих интерфейсов. Когда это произойдет, о второй ошибке сообщат, так как эти интерфейсы всегда сообщают о новом результате. Чтобы избежать этого, каждый поток может получить исключительное использование соединения с базой данных D вызовом sqlite3_mutex_enter( sqlite3_db_mutex(D)) до начала использования D и вызвать sqlite3_mutex_leave (sqlite3_db_mutex(D)) после того, как все обращения к интерфейсам, перечисленным здесь, будут закончены.

Если интерфейс терпит неудачу с SQLITE_MISUSE, это означает, что интерфейс был вызван неправильно приложением. В этом случае код ошибки и сообщение могут или не могут быть установлены.

---

Восстановление запроса SQL

const char *sqlite3_sql(sqlite3_stmt *pStmt);
char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
#ifdef SQLITE_ENABLE_NORMALIZE
const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
#endif

sqlite3_sql(P) возвращает указатель на копию кода на SQL UTF-8, используемого, чтобы создать подготовленный запрос P, если P был создан sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2() или sqlite3_prepare16_v3(). sqlite3_expanded_sql(P) возвращает указатель на последовательность UTF-8, содержащую код на SQL подготовленного запроса P с раскрытыми связанными параметрами. sqlite3_normalized_sql(P) возвращает указатель на последовательность UTF-8, содержащую нормализованный код на SQL подготовленного запроса P. Семантика, используемая, чтобы нормализовать SQL-оператор, не указана и подлежит изменению. Как минимум литеральные значения будут заменены подходящими заполнителями.

Например, если подготовленный запрос создается, используя код на SQL "SELECT $abc,:xyz" и если параметр $abc связан с целым числом 2345, а параметр :xyz не связан, то sqlite3_sql() возвратит исходную строку, "SELECT $abc,:xyz", но sqlite3_expanded_sql() вернет "SELECT 2345,NULL".

sqlite3_expanded_sql() вернет NULL, если недостаточно память доступно, чтобы хранить результат или если результат превысил бы максимальную длину строки, определенную SQLITE_LIMIT_LENGTH.

Выбор времени компиляции SQLITE_TRACE_SIZE_LIMIT ограничивает размер связанных расширений параметра. Выбор времени компиляции SQLITE_OMIT_TRACE заставляет sqlite3_expanded_sql() всегда вернуть NULL.

Последовательностями, возвращенными sqlite3_sql(P) и sqlite3_normalized_sql(P), управляет SQLite и автоматически освобождает, когда подготовленный запрос завершен. Последовательность, возвращенная sqlite3_expanded_sql(P), получена из sqlite3_malloc() и должна быть освобождена приложением, передав ее в sqlite3_free().

sqlite3_normalized_sql() только доступен, если выбор времени компиляции SQLITE_ENABLE_NORMALIZE определяется.

---

Переведите имена файлов

const char *sqlite3_filename_database(sqlite3_filename);
const char *sqlite3_filename_journal(sqlite3_filename);
const char *sqlite3_filename_wal(sqlite3_filename);

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

Если F это название файла базы данных, файла журнала или файла WAL, переданного ядром SQLite в VFS, то sqlite3_filename_database(F) возвращает название соответствующего файла базы данных.

Если F это название файла базы данных, файла журнала или файла WAL, переданного ядром SQLite в VFS, или если F это имя файла базы данных, полученное из sqlite3_db_filename(), то sqlite3_filename_journal(F) возвращает название соответствующего файла журнала обратной перемотки.

Если F это название файла базы данных, файла журнала или файла WAL, который был передан ядром SQLite в VFS, или если F это имя файла базы данных, полученное из sqlite3_db_filename(), то sqlite3_filename_wal(F) возвращает название соответствующего файла WAL.

Во всех вышеупомянутых ситуациях, если F не название базы данных, журнала или имени файла WAL, переданного в VFS от ядра SQLite и F, не возвращаемое значение от sqlite3_db_filename(), результат не определен и вероятно нарушение доступа к памяти.

---

Подсистема выделения памяти

void *sqlite3_malloc(int);
void *sqlite3_malloc64(sqlite3_uint64);
void *sqlite3_realloc(void*, int);
void *sqlite3_realloc64(void*, sqlite3_uint64);
void sqlite3_free(void*);
sqlite3_uint64 sqlite3_msize(void*);

Ядро SQLite использует эти три функции для всех его собственных потребностей распределения внутренней памяти. "Ядро" в предыдущем предложении не включает операционную систему и специфичную VFS. Windows VFS использует нативные malloc() и free().

sqlite3_malloc() возвращает указатель на блок памяти, по крайней мере N байт в длину, где N параметр. Если sqlite3_malloc() не может получить достаточную свободную память, он возвращает NULL. Если параметр N = 0 или отрицателен, sqlite3_malloc() возвращает NULL.

sqlite3_malloc64(N) обычно работает точно так же, как sqlite3_malloc(N), но N это unsigned 64-bit integer вместо signed 32-bit integer.

sqlite3_free() с указателем, ранее возвращенным sqlite3_malloc() или sqlite3_realloc(), освобождает память так, чтобы это могло бы быть снова использовано. sqlite3_free() ничего не делает, если вызван с NULL. Передача NULL в sqlite3_free() безопасна. Будучи освобожденной, память не должна быть прочитана или написана. Даже чтение ранее освобожденной памяти могло бы привести к ошибке сегментации или другой серьезной ошибке. Повреждение памяти, ошибка сегментации или другая серьезная ошибка могли бы возникнуть, если вызывают sqlite3_free() с указателем не-NULL, который не был получен из sqlite3_malloc() или sqlite3_realloc().

sqlite3_realloc(X,N) пытается изменить размеры предшествующего выделения памяти X, чтобы быть по крайней мере N байтами. Если X параметр для sqlite3_realloc(X,N) = NULL, его поведение идентично sqlite3_malloc(N). Если N для sqlite3_realloc(X,N) = 0 или отрицателен, поведение точно то же самое, как у sqlite3_free(X). sqlite3_realloc(X,N) возвращает указатель на выделение памяти по крайней мере N байт в размере или NULL, если недостаточно памяти. Если M это размер предшествующего распределения, то min(N,M) байт предшествующего распределения копируются в начало буфера, возвращенного sqlite3_realloc(X,N), и предшествующее распределение освобождено. Если sqlite3_realloc(X,N) вернет NULL и N положительный, то предшествующее распределение не освобождено.

sqlite3_realloc64(X,N) работает аналогично sqlite3_realloc(X,N), но N это 64-bit unsigned integer вместо 32-bit signed integer.

Если X это выделение памяти, ранее полученное из sqlite3_malloc(), sqlite3_malloc64(), sqlite3_realloc() или sqlite3_realloc64(), sqlite3_msize(X) вернет размер того выделения памяти в байтах. Значение, возвращенное sqlite3_msize(X), могло бы быть больше, чем заказанное число байтов, когда X был ассигнован. Если X = NULL, то sqlite3_msize(X) вернет 0. Если X указывает на что-то, что не является началом выделения памяти, или если это указывает на раньше действительное выделение памяти, которое было освобождено, то поведение sqlite3_msize(X) не определено и возможно вредно.

Память, возвращенная sqlite3_malloc(), sqlite3_realloc(), sqlite3_malloc64() и sqlite3_realloc64(), всегда выравнивается по крайней мере с 8-байтовой границей или с 4-байтовой границей, если выбор времени компиляции SQLITE_4_BYTE_ALIGNED_MALLOC использован.

Аргументами указателя sqlite3_free() и sqlite3_realloc() может быть NULL или иные указатели, полученные из предшествующего sqlite3_malloc() или sqlite3_realloc(), которые еще не были освобождены.

Приложение не должно читать или писать любую часть блока памяти после того, как это было освобождено sqlite3_free() или sqlite3_realloc().

---

Процедуры для удобного управления запросами

int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);
void sqlite3_free_table(char **result);

Это устаревший интерфейс, который сохранен для совместимости. Использование этого интерфейса не рекомендуется.

Определение: таблица результата это структура данных в оперативной памяти, созданная sqlite3_get_table(). Таблица результатов хранит запись полных результатов от одного или более запросов.

У таблицы концептуально есть много строк и колонок. Но эти числа не часть самой таблицы результата. Эти числа получены отдельно. Допустим, N количество строк, а M количество колонок.

Таблица результата это множество указателей на законченные нолем последовательности UTF-8. Есть (N+1)*M элементов во множестве. Первые указатели M указывают на законченные нолем последовательности, которые содержат названия колонок. Остающиеся записи указывают на результаты запроса. Значения NULL указывают на NULL. Все другие значения находятся в их UTF-8 законченным нолем строковом представлении, как возвращено sqlite3_column_text().

Таблица результата могла бы состоять из одного или более выделений памяти. Небезопасно передать его непосредственно sqlite3_free(). Таблица результата должна быть освобождена, используя sqlite3_free_table().

Как пример формата таблицы результата, предположите, что результаты запроса следующие:

Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21

Есть две колонки (M == 2) и три строки (N==3). Таким образом у таблицы результата есть 8 записей. Предположим, что таблица результата сохранена во множестве, названном azResult. Тогда azResult имеет это содержание:

azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";

sqlite3_get_table() оценивает один или несколько отделенных точкой с запятой SQL-операторов в законченной нолем последовательности UTF-8 ее 2-го параметра и возвращает таблицу результата указателю в ее 3-м параметре.

После того, как приложение закончило работу с результатом sqlite3_get_table(), это должно передать указатель таблицы результата в sqlite3_free_table(), чтобы освободить память, которая была выделена. Из-за того, как sqlite3_malloc() вызывается в sqlite3_get_table() функция запроса не должна пытаться вызвать напрямую sqlite3_free(). Только sqlite3_free_table() is в состоянии освободить память правильно и безопасно.

sqlite3_get_table() осуществляется как обертка вокруг sqlite3_exec(). sqlite3_get_table() не имеет доступа ни к каким внутренним структурам данных SQLite. Это использует только открытый интерфейс, определенный здесь. Как следствие ошибки, которые происходят в слое обертки за пределами внутреннего sqlite3_exec(), не отражены в последующих sqlite3_errcode() или sqlite3_errmsg().

---

Функция вспомогательных данных

void *sqlite3_get_auxdata(sqlite3_context*, int N);
void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

Эти функции могут использоваться (несовокупными) функциями SQL, чтобы связать вспомогательные данные со значениями аргументов. Если то же самое значение аргумента передается к многократным вызовам той же самой функции SQL во время выполнения запросов при некоторых обстоятельствах, связанные вспомогательные данные могли бы быть сохранены. Пример того, где это могло бы быть полезно, находится в функции соответствия регулярного выражения. Скомпилированная версия регулярного выражения может быть сохранена как вспомогательные данные, связанные со строкой образца. Тогда, пока строка образца остается тем же самым, собранное регулярное выражение может быть снова использовано в многократных вызовах той же самой функции.

sqlite3_get_auxdata(C,N) возвращает указатель на вспомогательные данные, связанные sqlite3_set_auxdata(C,N,P,X) со значением N-го аргумента к определенной применением функции. N = 0 для крайнего левого аргумента функции. Если нет никаких вспомогательных данных, связанных с аргументом функции, sqlite3_get_auxdata(C,N) вернет NULL.

sqlite3_set_auxdata(C,N,P,X) сохраняет P как вспомогательные данные для аргумента N определенной применением функции. Последующие вызовы sqlite3_get_auxdata(C,N) вернут P из нового вызова sqlite3_set_auxdata(C,N,P,X), если вспомогательные данные все еще действительны или NULL, если от вспомогательных данных отказались. После каждого вызова sqlite3_set_auxdata(C,N,P,X), где X не NULL, SQLite вызовет функцию деструктора X с параметром P точно однажды, когда от вспомогательных данных откажутся. SQLite свободен отказаться от вспомогательных данных в любое время, включая:

• Когда соответствующий параметр функции изменяется
• Когда sqlite3_reset() или sqlite3_finalize() вызывают для SQL-оператора
• Когда sqlite3_set_auxdata() вызван снова на том же самом параметре
• во время оригинального вызова sqlite3_set_auxdata(), когда ошибка распределения памяти происходит.

Отметьте последний момент в частности. Деструктор X в sqlite3_set_auxdata(C,N,P,X) можно было бы немедленно вызвать перед возвратом sqlite3_set_auxdata(). Следовательно, sqlite3_set_auxdata() нужно вызвать около конца реализации функции, и реализация функции не должна делать использование P после того, как вызван sqlite3_set_auxdata().

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

Значение параметра N должно быть неотрицательным. Будущие улучшения могут использовать отрицательные значения N, чтобы определить новые виды поведения кэширования функции.

Это нужно вызвать от того же потока, в котором работает функция SQL.

См. также: sqlite3_get_clientdata() и sqlite3_set_clientdata().

---

Данные клиента соединения с базой данных

void *sqlite3_get_clientdata(sqlite3*,const char*);
int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));

Эти функции используются, чтобы связать один или несколько названных указателей с соединением с базой данных. Вызов sqlite3_set_clientdata(D,N,P,X) заставляет указатель P быть присоединенным к соединению с базой данных D, используя имя N. Вызов sqlite3_get_clientdata(D,N) возвратит копию указателя P или NULL, если не было никаких предшествующих вызовов sqlite3_set_clientdata() с теми же самыми значениями D и N. Имена сравнены, используя strcmp() и таким образом чувствительны к регистру.

Если P и X оба не NULL, деструктор X вызван с аргументом P в следующих случаях:

• Ошибка out-of-memory происходит во время sqlite3_set_clientdata(), который пытается зарегистрировать указатель P.
• Вызов sqlite3_set_clientdata(D,N,P,X) сделан с темм же самыми параметрами D и N.
• Завершение соединения с базой данных. SQLite не делает гарантий порядка, в котором деструктор вызывают, только то, что все деструктора вызовут точно однажды в какой-то момент во время процесса закрытия соединения с базой данных.

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

Нет никакого предела (кроме доступной памяти) числа различных указателей данных клиента (с различными именами), который может быть присоединен к связи единой базы данных. Однако внедрение оптимизировано для случая наличия только одного или двух различных имен данных клиента.

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

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

Данные клиента соединения с базой данных доступны только для версии SQLite version 3.44.0 (2023-11-01) и позже.

См. также: sqlite3_set_auxdata() и sqlite3_get_auxdata().

---

Наложите ограничение на размер кучи

sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);

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

sqlite3_soft_heap_limit64() устанавливает и/или запрашивает мягкий предел суммы памяти кучи, которая может быть ассигнована SQLite. SQLite стремится держать использование памяти кучи ниже мягкого предела кучи, сокращая количество страниц в кэше страницы, когда использование памяти кучи приближается к пределу. Мягкий предел кучи "мягкий", потому что даже при том, что SQLite стремится остаться ниже предела, это превысит предел, а не произведет ошибку SQLITE_NOMEM. Другими словами, мягкий предел кучи только консультативный.

sqlite3_hard_heap_limit64(N) устанавливает твердую верхнюю границу в N байт на объем памяти, который будет ассигнован. sqlite3_hard_heap_limit64(N) аналогичен sqlite3_soft_heap_limit64(N), но выделения памяти потерпят неудачу, когда этот предел кучи будет достигнут.

Возвращаемое значение от обоих sqlite3_soft_heap_limit64() и sqlite3_hard_heap_limit64() является размером предела кучи до вызова или отрицательным значением в случае ошибки. Если аргумент N отрицателен, никакое изменение не внесено в предел кучи. Следовательно, текущий размер пределов кучи может быть определен вызовом sqlite3_soft_heap_limit64(-1) или sqlite3_hard_heap_limit(-1).

Установление пределов кучи к нолю отключает механизм ограничителя кучи.

Мягкий предел кучи не может быть больше, чем жесткий. Если жесткий предел кучи позволен, и sqlite3_soft_heap_limit(N) вызван со значением N, который больше, чем жесткий предел кучи, мягкий предел кучи устанавливается к значению жесткого предела кучи. Мягкий предел кучи автоматически позволен каждый раз, когда жесткий предел кучи позволен. Когда sqlite3_hard_heap_limit64(N) вызван, и мягкий предел кучи вне диапазона 1..N, мягкий предел кучи устанавливается к N. Вызов sqlite3_soft_heap_limit64(0), когда жесткий предел кучи позволен, делает мягкий предел кучи равным жесткому пределу кучи.

Пределы выделения памяти могут также быть переопределены, используя PRAGMA soft_heap_limit и PRAGMA hard_heap_limit.

Пределы кучи не проведены в жизнь в текущем внедрении, если одно или больше следующих условий верны:

• Предельное значение установлено в ноль.
• Учет памяти отключен, используя комбинацию sqlite3_config( SQLITE_CONFIG_MEMSTATUS,...) и SQLITE_DEFAULT_MEMSTATUS.
• Альтернативное внедрение кэша страницы определяется, используя sqlite3_config( SQLITE_CONFIG_PCACHE2, ...).
• Кэш страницы ассигнует от его собственного пула памяти, поставляемого sqlite3_config( SQLITE_CONFIG_PAGECACHE, ...), а не от кучи.

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

---

Инициализируйте библиотеку SQLite

int sqlite3_initialize(void);
int sqlite3_shutdown(void);
int sqlite3_os_init(void);
int sqlite3_os_end(void);

sqlite3_initialize() инициализирует библиотеку SQLite. sqlite3_shutdown() освобождает любые ресурсы, которые были ассигнованы sqlite3_initialize(). Это разработано, чтобы помочь в инициализации процесса и закрытии во встроенных системах. Приложения рабочей станции, используя SQLite обычно не должны вызывать ничего из этого.

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

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

sqlite3_initialize() ориентирован на многопоточное исполнение, но не sqlite3_shutdown(). sqlite3_shutdown() нужно вызвать только от единственного потока. Все открытые соединения с базой данных должны быть закрыты, и все другие ресурсы SQLite должны быть освобождены до вызова sqlite3_shutdown().

Среди прочего, sqlite3_initialize() вызовет sqlite3_os_init(). Аналогично sqlite3_shutdown() вызовет sqlite3_os_end().

sqlite3_initialize() вернет SQLITE_OK при успехе. Если по некоторым причинам sqlite3_initialize() не может инициализировать библиотеку (возможно, это не смогло ассигновать необходимый ресурс, такой как mutex), это возвращает код ошибки, а не SQLITE_OK.

sqlite3_initialize() вызывает внутренне много других интерфейсов SQLite так что приложение обычно не должно вызывать напрямую sqlite3_initialize(). Например, sqlite3_open() вызывает sqlite3_initialize(), таким образом, библиотека SQLite будет автоматически инициализирована, когда sqlite3_open() вызовут, если это не было инициализировано. Однако, если SQLite собран с выбором времени компиляции SQLITE_OMIT_AUTOINIT, автоматические вызовы sqlite3_initialize() опущены, и приложение должно вызвать sqlite3_initialize() непосредственно до использования любого другого интерфейса SQLite. Для максимальной мобильности рекомендуется, чтобы запросы всегда вызвали sqlite3_initialize() непосредственно до использования любого другого интерфейса SQLite. Будущие выпуски SQLite могут потребовать этого. Другими словами, поведение, показанное, когда SQLite собран с SQLITE_OMIT_AUTOINIT, могло бы стать поведением по умолчанию в некотором будущем выпуске SQLite.

sqlite3_os_init() делает инициализацию библиотеки SQLite для операционной системы. sqlite3_os_end() отменяет эффект sqlite3_os_init(). Типичные задачи, выполненные этим установленным порядком, включают распределение или освобождение статических ресурсов, инициализацию глобальных переменных, настраивая умолчание модуля sqlite3_vfs или настраивая конфигурацию по умолчанию, используя sqlite3_config().

Применение никогда не должно вызывать sqlite3_os_init() или sqlite3_os_end(). Применение должно вызвать только sqlite3_initialize() и sqlite3_shutdown(). sqlite3_os_init() вызывает автоматически sqlite3_initialize() и sqlite3_os_end() вызывает sqlite3_shutdown(). Соответствующие внедрения для sqlite3_os_init() и sqlite3_os_end() встроены в SQLite, когда это собрано для Unix, Windows или OS/2. Когда построено для других платформ (используя выбор времени компиляции SQLITE_OS_OTHER=1), приложение должно поставлять подходящее внедрение для sqlite3_os_init() и sqlite3_os_end(). Прикладная предоставленная реализация sqlite3_os_init() или sqlite3_os_end() должна возвратить SQLITE_OK при успехе и некоторый другой код ошибки при сбое.

---

Прервите продолжительный запрос

void sqlite3_interrupt(sqlite3*);
int sqlite3_is_interrupted(sqlite3*);

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

Безопасно вызвать это из потока, отличающегося от потока, который в настоящее время управляет операцией по базе данных. Но небезопасно вызвать это с соединением с базой данных, которое закрывается или могло бы закрыться прежде возврата sqlite3_interrupt().

Если операция SQL почти закончена в то время, когда вызвана sqlite3_interrupt(), она может и не прерваться.

Операция SQL, которая прервана, возвратит SQLITE_INTERRUPT. Если прерванной операцией SQL будет INSERT, UPDATE или DELETE в явной транзакции, то вся транзакция будет отменена до прежнего уровня автоматически.

sqlite3_is_interrupted(D) может использоваться, чтобы определить, является ли прерывание в настоящее время активным для соединения с базой данных D. Это возвращает 1, если прерывание в настоящее время активен или 0 иначе.

---

Проверка ключевого слова SQL

int sqlite3_keyword_count(void);
int sqlite3_keyword_name(int,const char**,int*);
int sqlite3_keyword_check(const char*,int);

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

sqlite3_keyword_count() возвращает количество отличных ключевых слов, понятых SQLite.

sqlite3_keyword_name(N,Z,L) находит N-е ключевое слово, делает *Z указателем на то ключевое слово, выраженное как UTF8, и пишет число байтов в ключевом слове в *L. Последовательность *Z не закончена нолем. sqlite3_keyword_name(N,Z,L) вернет SQLITE_OK, если N в границах и SQLITE_ERROR иначе. Если Z или L = NULL или недопустимые указатели, тогда действие sqlite3_keyword_name(N,Z,L) не определено.

sqlite3_keyword_check(Z,L) проверяет, действительно ли L-байтный идентификатор UTF8, на который указывает Z, является ключевым словом, возвращая отличное от нуля значение, если это так, и ноль если нет.

Анализатор, используемый SQLite, прощающий. Часто возможно использовать ключевое слово в качестве идентификатора, поскольку долгое использование как таковое не приводит к двусмысленности парсинга. Например, "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" принято SQLite и составляет новую таблицу под названием "BEGIN" с тремя колонками "REPLACE", "PRAGMA" и "END". Тем не менее, наиболее успешная практика должна избегать использования ключевых слов как идентификаторов. Общие методы избегать столкновения имени и ключевого слова включают:

• Поместите все имена идентификатора в двойных кавычках. Это официальный режим SQL избежать имен идентификатора.
• Вставьте имена идентификатора в [...]. Это не стандартный SQL, но это то, что делает SQL Server и таким образом, много программистов используют эту технику.
• Начните каждый идентификатор с "Z", поскольку никакие ключевые слова SQL не начинаются с "Z".
• Включайте цифру где-нибудь в каждое имя идентификатора.

Обратите внимание на то, что количество ключевых слов, понятых SQLite, может зависеть от вариантов времени компиляции. Например, "VACUUM" это не ключевое слово, если SQLite собран с -DSQLITE_OMIT_VACUUM. Кроме того, новые ключевые слова могут быть добавлены к будущим выпускам SQLite.

---

Номера версий библиотеки времени выполнения

SQLITE_EXTERN const char sqlite3_version[];
const char *sqlite3_libversion(void);
const char *sqlite3_sourceid(void);
int sqlite3_libversion_number(void);

Эти интерфейсы предоставляют ту же самую информацию, как С-макросы препроцессора SQLITE_VERSION, SQLITE_VERSION_NUMBER и SQLITE_SOURCE_ID, но связаны с библиотекой вместо заголовочного файла. Осторожные программисты могли бы включать assert(), чтобы проверить, что значения, возвращенные этими интерфейсами, соответствуют макросу в заголовке, и таким образом гарантировать, что приложение собрано с соответствием библиотеке и заголовочным файлам.

assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

Строковая константа sqlite3_version[] содержит текст макроса SQLITE_VERSION. Функция sqlite3_libversion() возвращает указатель на строковую константу sqlite3_version[]. sqlite3_libversion() обеспечивается для использования в DLL, так как у пользователей DLL обычно нет прямого доступа к строковым константам в DLL. sqlite3_libversion_number() вернет integer, равный SQLITE_VERSION_NUMBER. sqlite3_sourceid() вернет указатель на строковую константу, значение которой совпадает с макросом SQLITE_SOURCE_ID . Кроме того, если SQLite строится, используя отредактированную копию объединения, то последние четыре знака хэша могли бы отличаться от SQLITE_SOURCE_ID.

См. также: sqlite_version() и sqlite_source_id().

---

Статистика распределителя памяти

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

SQLite обеспечивает эти два интерфейса для сообщения о статусе sqlite3_malloc(), sqlite3_free() и sqlite3_realloc(), которые формируют встроенную подсистему выделения памяти.

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

Высшая точка памяти перезагружается к текущему значению sqlite3_memory_used() если и только если параметр sqlite3_memory_highwater() = true. Значение, возвращенное sqlite3_memory_highwater(1), является высшей точкой до сброса.

---

Функции печати отформатированной строки

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);

Этот аналог функций "printf()" стандартной библиотеки для C. Это понимает большинство общих параметров форматирования из стандартной библиотеки printf() плюс некоторые дополнительные нестандартные форматы (%q, %Q, %w и %z).

sqlite3_mprintf() и sqlite3_vmprintf() пишут свои результаты в память, полученную из sqlite3_malloc64(). Последовательности, возвращенные этими двумя функциями, должны быть освобождены sqlite3_free(). Обе возвращают NULL, если sqlite3_malloc64() не может ассигновать достаточно памяти, чтобы хранить получившуюся строку.

sqlite3_snprintf() аналог "snprintf()" из стандартной библиотеки для C. Результат написан в буфер, поставляемый как второй параметр, размер которого дан первым параметром. Обратите внимание на то, что порядок первых двух параметров полностью изменен от snprintf(). Это исторический несчастный экземпляр, который не может быть исправлен, не ломая обратную совместимость. Отметьте также, что sqlite3_snprintf() возвращает указатель на свой буфер вместо количества знаков, на самом деле написанных в буфер. Мы признаем, что количество знаков было бы более полезным возвращаемым значением, но мы не можем изменить sqlite3_snprintf(), не ломая обратную совместимость.

Пока размер буфера больше, чем ноль, sqlite3_snprintf() гарантирует, что буфер всегда заканчивается нолем. Первый параметр "n" это является полным размером буфера, включая пространство для нулевого терминатора. Таким образом, самая длинная последовательность, которая может быть полностью написана, будет n-1 знаками.

sqlite3_vsnprintf() является varargs-версией sqlite3_snprintf().

См. также: built-in printf(), Функция SQL printf()

---

Mutexes

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);

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

Исходный код SQLite содержит многократные внедрения этого mutex. Соответствующее внедрение отобрано автоматически во время компиляции. Следующие внедрения доступны в ядре SQLite:

• SQLITE_MUTEX_PTHREADS
• SQLITE_MUTEX_W32
• SQLITE_MUTEX_NOOP

SQLITE_MUTEX_NOOP это набор функций, который не делает никакой реальной блокировки и подходит для использования в однопоточном применении. SQLITE_MUTEX_PTHREADS и SQLITE_MUTEX_W32 подходят для использования на Unix и Windows.

Если SQLite собран с определенным макросом препроцессора SQLITE_MUTEX_APPDEF ("-DSQLITE_MUTEX_APPDEF=1"), то никакое mutex внедрение не включено в библиотеку. В этом случае приложение должно поставлять свой mutex, используя выбор SQLITE_CONFIG_MUTEX в функции sqlite3_config() перед вызовом sqlite3_initialize() или любой другой функции sqlite3_, вызывающей sqlite3_initialize().

sqlite3_mutex_alloc() ассигнует новый mutex и возвращает указатель на него. sqlite3_mutex_alloc() возвращает NULL, если это не может ассигновать требуемый mutex. Аргумент sqlite3_mutex_alloc() должен быть одной из этих констант целого числа:

• SQLITE_MUTEX_FAST
• SQLITE_MUTEX_RECURSIVE
• SQLITE_MUTEX_STATIC_MAIN
• SQLITE_MUTEX_STATIC_MEM
• SQLITE_MUTEX_STATIC_OPEN
• SQLITE_MUTEX_STATIC_PRNG
• SQLITE_MUTEX_STATIC_LRU
• SQLITE_MUTEX_STATIC_PMEM
• SQLITE_MUTEX_STATIC_APP1
• SQLITE_MUTEX_STATIC_APP2
• SQLITE_MUTEX_STATIC_APP3
• SQLITE_MUTEX_STATIC_VFS1
• SQLITE_MUTEX_STATIC_VFS2
• SQLITE_MUTEX_STATIC_VFS3

Первые две константы (SQLITE_MUTEX_FAST и SQLITE_MUTEX_RECURSIVE) заставляют sqlite3_mutex_alloc() создавать новый mutex. Новый mutex рекурсивный, когда SQLITE_MUTEX_RECURSIVE используется, но не обязательно поэтому, когда SQLITE_MUTEX_FAST используется. Внедрение mutex не должно делать различие между SQLITE_MUTEX_RECURSIVE и SQLITE_MUTEX_FAST, если это не хочет. SQLite будет просить рекурсивный mutex только в случаях, где он ему действительно нужен. Если более быстрое нерекурсивное внедрение mutex доступно на серверной платформе, подсистема mutex могла бы возвратить такой mutex в ответ на SQLITE_MUTEX_FAST.

Другие позволенные параметры sqlite3_mutex_alloc() (что-либо кроме SQLITE_MUTEX_FAST и SQLITE_MUTEX_RECURSIVE) каждый возвращают указатель на статическое существование ранее mutex. Девять статических mutexes используются текущей версией SQLite. Будущие версии SQLite могут добавить дополнительный статический mutexes. Статические mutexes только для внутреннего использования SQLite. Приложения, которые используют SQLite mutexes, должны использовать только динамический mutexes, возвращенный SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE.

Обратите внимание на то, что, если один из динамических mutex параметров (SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE) используется, тогда sqlite3_mutex_alloc() возвращает различный mutex при каждом запросе. Для статических типов mutex тот же самый mutex возвращен при каждом запросе, у которого есть то же самое число типа.

sqlite3_mutex_free() освобождает ранее ассигнованный динамический mutex. Попытка освободить статический mutex приводит к неопределенному поведению.

sqlite3_mutex_enter() и sqlite3_mutex_try() пытаются войти в mutex. Если другой поток уже будет в mutex, то sqlite3_mutex_enter() заблокирует, а sqlite3_mutex_try() вернет SQLITE_BUSY. sqlite3_mutex_try() вернет SQLITE_OK после успешного входа. Mutexes, созданный с использованием SQLITE_MUTEX_RECURSIVE, может быть введен многократно тем же потоком. В таких случаях из mutex нужно выйти равное количество раз, прежде чем другой поток сможет войти. Если тот же самый поток пытается войти в какой-либо mutex кроме SQLITE_MUTEX_RECURSIVE несколько раз, поведение не определено.

Некоторые системы (например, Windows 95) не поддерживают операцию, осуществленную sqlite3_mutex_try(). На тех системах sqlite3_mutex_try() будет всегда возвращать SQLITE_BUSY. Ядро SQLite использует sqlite3_mutex_try() только как оптимизацию, таким образом, это приемлемое поведение.

sqlite3_mutex_leave() выходит из mutex, который был ранее введен тем же самым потоком. Поведение не определено, если mutex в настоящее время не вводится вызывающим потоком или в настоящее время не ассигнуется.

Если аргумент sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave() или sqlite3_mutex_free() это NULL, то любая из этих функций не делает ничего.

См. также: sqlite3_mutex_held() и sqlite3_mutex_notheld().

---

Режимы проверки Mutex

#ifndef NDEBUG
int sqlite3_mutex_held(sqlite3_mutex*);
int sqlite3_mutex_notheld(sqlite3_mutex*);
#endif

sqlite3_mutex_held() и sqlite3_mutex_notheld() предназначается для использования внутри assert(). Ядро SQLite никогда не использует эту хранимую процедуру, кроме внутренней части assert(). Ядро SQLite обеспечивает внедрения для этого установленного порядка только когда оно собрано с флагом SQLITE_DEBUG. Внешние mutex внедрения должны обеспечивать эту хранимую процедуру только если SQLITE_DEBUG определяется и NDEBUG не определяется.

Это должно возвратить true, если mutex в их аргументе проведен или не проведен, соответственно, вызывающим потоком.

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

Если аргумент sqlite3_mutex_held() это NULL, вернется 1. Это кажется парадоксальным, так как mutex не может быть проведен, если он не существует. Но причина, по которой mutex не существует, состоит в том, что сборка не использует mutexes. И мы не хотим, чтобы assert(), содержащий запрос sqlite3_mutex_held(), потерпел неудачу, таким образом, возвращение отличное от нуля, правильно. sqlite3_mutex_notheld() должен также возвратить 1, когда ему дали NULL.

---

Открытие нового соединения с базой данных

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);

int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);

int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

Это открывает файл базы данных SQLite, как определено аргументом имени файла. Аргумент имени файла интерпретируется как UTF-8 для sqlite3_open() и sqlite3_open_v2() или UTF-16 в родном порядке байтов для sqlite3_open16(). Обработчик соединения с базой данных обычно возвращается в *ppDb, даже если ошибка происходит. Единственное исключение это если SQLite не может ассигновать память, чтобы хранить объект sqlite3, NULL впишут в *ppDb вместо указателя на объект sqlite3. Если база данных открыта (и/или создана) успешно, то вернется SQLITE_OK. Иначе вернется код ошибки. sqlite3_errmsg() или sqlite3_errmsg16() может использоваться, чтобы получить английское языковое описание ошибки после неудачи любого из sqlite3_open().

Кодировка по умолчанию будет UTF-8 для баз данных, созданных, используя sqlite3_open() или sqlite3_open_v2(). Кодировка по умолчанию для баз данных, созданных, используя sqlite3_open16(), это UTF-16 в родном порядке байт.

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

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

SQLITE_OPEN_READONLY

База данных открыта в режиме только для чтения. Если база данных не существует, ошибка возвращена.

SQLITE_OPEN_READWRITE

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

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE

База данных открыта для чтения и и записи, причем создается, если это еще не существует. Это поведение, которое всегда используется для sqlite3_open() и sqlite3_open16().

В дополнение к необходимым флагам также поддерживаются следующие дополнительные флаги:

SQLITE_OPEN_URI

Имя файла может интерпретироваться как URI, если этот флаг установлен.

SQLITE_OPEN_MEMORY

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

SQLITE_OPEN_NOMUTEX

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

SQLITE_OPEN_FULLMUTEX

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

SQLITE_OPEN_SHAREDCACHE

База данных открыта с включенным общим кэшем, отвергая параметры умолчания разделенного кэша, обеспеченные sqlite3_enable_shared_cache(). Использованию общего режима кэширования и следовательно общие возможности кэша могут быть опущены в ряде сборок SQLite. В таких случаях этот выбор ничего не делает.

SQLITE_OPEN_PRIVATECACHE

База данных открыта с запретом бощего кэша , отвергая параметры умолчания разделенного кэша, обеспеченные sqlite3_enable_shared_cache().

SQLITE_OPEN_EXRESCODE

Соединение с базой данных подходит в "расширенном кодовом режиме результата". Другими словами, база данных ведет себя, как если выполнено sqlite3_extended_result_codes(db,1) на соединении с базой данных, как только связь создается. В дополнение к урегулированию расширенного кодового режима результата этот флаг также заставляет sqlite3_open_v2() возвращать расширенный код результата.

SQLITE_OPEN_NOFOLLOW

Имени файла базы данных не позволяют содержать символьную ссылку.

Если 3-й параметр sqlite3_open_v2() не является одной из необходимых комбинаций, показанных выше, произвольно объединенной с другими SQLITE_OPEN_* bits, поведение не определено. Исторические версии SQLite тихо игнорировали избыточные биты в параметре флагов sqlite3_open_v2(), однако то поведение не могло бы быть осуществлено в будущих версиях SQLite и таким образом приложения не должны полагаться на него. Отметьте в особенности, что флаг SQLITE_OPEN_EXCLUSIVE ничего не делает в sqlite3_open_v2(). SQLITE_OPEN_EXCLUSIVE НЕ заставляют открытие терпеть неудачу, если база данных уже существует. SQLITE_OPEN_EXCLUSIVE предназначается для использования только интерфейсом VFS, но не sqlite3_open_v2().

Четвертый параметр sqlite3_open_v2() является названием объекта sqlite3_vfs, который определяет интерфейс операционной системы, который должно использовать новое соединение с базой данных. Если четвертый параметр NULL, тогда применяется умолчание объекта sqlite3_vfs.

Если имя файла ":memory:", частная, временная база данных в памяти создается для связи. Эта база данных в памяти исчезнет, когда соединение с базой данных будет закрыто. Будущие версии SQLite могли бы использовать дополнительные специальные имена файлов, которые начинаются с ":". Рекомендуется, когда имя файла базы данных на самом деле начинается с ":", вы должны поставить префикс имени файла с таким путем, как "./", чтобы избежать двусмысленности.

Если имя файла будет пустой строкой, то частная, временная база данных на диске будет создана. Эта частная база данных будет автоматически удалена, как только соединение с базой данных закрывается.

Имена файлов URI

Если имена файлов URI позволены и аргумент имени файла начинается с "file:", тогда имя файла интерпретируется как URI. Интерпретация имени файла URI позволена, если флаг SQLITE_OPEN_URI установлен в третьем аргументе sqlite3_open_v2() или если это было позволено глобально, используя выбор SQLITE_CONFIG_URI в методе sqlite3_config() или опцией компиляции SQLITE_USE_URI. Интерпретация имени файла URI выключена по умолчанию, но будущие выпуски SQLite могли бы позволить интерпретацию имени файла URI по умолчанию. См. здесь подробности.

Имена файлов URI разобраны согласно RFC 3986. Если URI содержит авторизацию, то это должна быть пустая строка или последовательность "localhost", иначе ошибка возвращена. Компонент фрагмента URI, если есть проигнорирован.

SQLite использует компонент контура URI как название дискового файла, который содержит базу данных. Если путь начинается с '/', то это интерпретируется как абсолютный путь. Если путь не начинается с '/' (подразумевается, что часть секции авторизации опущена в URI), тогда путь интерпретируется как относительный. В Windows первый компонент абсолютного пути это спецификация привода (например, "C:").

Компонент запроса URI может содержать параметры, которые интерпретируются самим SQLite или реализацией VFS. SQLite и его встроенный VFS интерпретируют следующие параметры запроса:

• vfs: Параметр "vfs" может использоваться, чтобы определить название объекта VFS, который обеспечивает интерфейс операционной системы, который должен использоваться, чтобы получить доступ к файлу базы данных на диске. Если этот выбор установлен в пустую строку, используется объект VFS по умолчанию. Определение неизвестного VFS является ошибкой. Если используется sqlite3_open_v2() и vfs выбор присутствует, то VFS, определенный выбором, имеет приоритет по значению, переданный как четвертый параметр sqlite3_open_v2().

• mode: Параметр режима может быть установлен в "ro", "rw", "rwc" или "memory". Попытка установить его в любое другое значение является ошибкой. Если указано "ro", то база данных открыта для доступа только для чтения, так же, как если бы флаг SQLITE_OPEN_READONLY был установлен в третьем аргументе sqlite3_open_v2(). Если выбор режима установлен в "rw", то база данных открыта для чтения-записи (но не создания), как будто установлено SQLITE_OPEN_READWRITE (но не SQLITE_OPEN_CREATE). Значение "rwc" эквивалентно урегулированию SQLITE_OPEN_READWRITE и SQLITE_OPEN_CREATE вместе. Если выбор режима установлен в "memory", база данных в памяти, которая никогда не читается или пишется на диск, используется. Ошибка определить значение для параметра режима, которое менее строгое, чем определенное флагами, переданными в третьем параметре sqlite3_open_v2().

• cache: параметр кэша может быть установлен в "shared" или "private". "shared" эквивалентно установке бита SQLITE_OPEN_SHAREDCACHE в аргументе флагов, переданном sqlite3_open_v2(). "private" эквивалентно установке бита SQLITE_OPEN_PRIVATECACHE. Если применяется sqlite3_open_v2() и параметр "cache" присутствует в имени файла URI, его значение отвергает любое поведение, которое требуют, устанавливая SQLITE_OPEN_PRIVATECACHE или SQLITE_OPEN_SHAREDCACHE.

• psow: Параметр psow указывает, переписывают ли свойство powersafe overwrite применительно к носителям, на которых находится файл базы данных.

• nolock: nolock это boolean параметр логического запроса который, если установлен отключает захват файла в режимах журнала обратной перемотки. Это полезно для доступа к базе данных по файловой системе, которая не поддерживает блокировку. Осторожно: повреждение базы данных могло бы возникнуть, если два или больше процесса пишут ту же самую базу данных, и любой из тех процессов использует nolock=1.

• immutable: immutable это boolean параметр логического запроса, который указывает, что файл базы данных хранится на носителе только для чтения. Если immutable установлен, SQLite предполагает, что файл базы данных не может быть изменен, даже процессом с более высокой привилегией, и таким образом, база данных открыта только для чтения, а все изменения отключены. Осторожно: указание immutable на файле базы данных, который на самом деле изменяется, может привести к неправильным результатам запроса и/или ошибкам SQLITE_CORRUPT. См. также: SQLITE_IOCAP_IMMUTABLE.

Определение неизвестного параметра в компоненте запроса URI не является ошибкой. Будущие версии SQLite могли бы понять дополнительные параметры запроса. См. здесь подробности.

Примеры имени файла URI

URI	Результат
file:data.db	Откройте файл "data.db" в текущем каталоге.
file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db	Откройте файл "/home/fred/data.db".
file://darkstar/home/fred/data.db	Ошибка. "darkstar" не признанная авторизация.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	Только Windows: Откройте файл "data.db" рабочего стола fred на диске C:. Обратите внимание на то, что экранировка %20 в этом примере не строго необходима: пробелы могут использоваться буквально в именах файлов URI.
file:data.db?mode=ro&cache=private	Откройте файл "data.db" в текущем каталоге для доступа только для чтения. Независимо от того, позволен ли общий режим кэширования по умолчанию, используйте частный кэш.
file:/home/fred/data.db?vfs=unix-dotfile	Откройте файл "/home/fred/data.db". Используйте специальный VFS "unix-dotfile", который использует точечные файлы вместо консультативной блокировки posix.
file:data.db?mode=readonly	Ошибка. "readonly" не действительная возможность для параметра "mode". Используйте "ro" вместо этого: "file:data.db?mode=ro".

Шестнадцатеричные escape-последовательности URI (%HH) поддерживаются в пути и запрашивают компоненты URI. Шестнадцатеричная escape-последовательность состоит из знака процента "%", сопровождаемого точно двумя шестнадцатеричными цифрами, определяющими значение октета. Прежде чем путь или компоненты запроса имени файла URI интерпретируются, они закодированы, используя UTF-8 и все шестнадцатеричные escape-последовательности, заменены единственным байтом, содержащим соответствующий октет. Если этот процесс производит недействительное кодирование UTF-8, результаты не определены.

Замечание для Windows: кодирование, используемое для аргумента имени файла sqlite3_open() и sqlite3_open_v2() должно быть UTF-8, независимо от того, какая кодовая страница в настоящее время определяется. Имена файлов, содержащие международные символы, должны быть преобразованы в UTF-8 до прохождения их в sqlite3_open() или sqlite3_open_v2().

Замечание для Windows Runtime: временный каталог должен быть установлен до запроса sqlite3_open() или sqlite3_open_v2(). Иначе различные особенности, которые требуют использования временных файлов, могут потерпеть неудачу.

См. также: sqlite3_temp_directory.

---

Перехват перед обновлением

#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
void *sqlite3_preupdate_hook(sqlite3 *db, void(*xPreUpdate)(
    void *pCtx,                   /* Copy of third arg to preupdate_hook() */
    sqlite3 *db,                  /* Database handle */
    int op,                       /* SQLITE_UPDATE, DELETE or INSERT */
    char const *zDb,              /* Database name */
    char const *zName,            /* Table name */
    sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */
    sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */
  ), void*);
int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_count(sqlite3 *);
int sqlite3_preupdate_depth(sqlite3 *);
int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_blobwrite(sqlite3 *);
#endif

Эти интерфейсы доступны только, если SQLite собран, используя выбор времени компиляции SQLITE_ENABLE_PREUPDATE_HOOK.

sqlite3_preupdate_hook() регистрирует функцию обратного вызова, которая вызвана до каждого INSERT, UPDATE и DELETE на таблице базы данных. Самое большее один перехват перед обновлением может быть зарегистрирован за один раз на связи единой базы данных, каждый вызов sqlite3_preupdate_hook() отвергает предыдущее урегулирование. Перехват перед обновлением отключен sqlite3_preupdate_hook() с NULL как второй параметр. Через третий параметр sqlite3_preupdate_hook() передают первый параметр к отзывам.

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

Второй параметр отзыва перед обновлением это указатель на соединение с базой данных, которое зарегистрировало перехват перед обновлением. Третий параметр к отзыву перед обновлением это одна из констант SQLITE_INSERT, SQLITE_DELETE или SQLITE_UPDATE, чтобы определить вид операции по обновлению, которая собирается произойти. Четвертый параметр отзыва перед обновлением задает название базы данных в рамках соединения с базой данных, которое изменяется. Это будет "main" для главной базы данных, "temp" для таблиц TEMP или имя, данное после ключевого слова AS в ATTACH. Пятый параметр определяет название таблицы, которая изменяется.

Для UPDATE или DELETE на таблице rowid шестой параметр0 является начальным rowid строки, изменяемой или удаленной. Для операции INSERT на таблице rowid или любой операции на таблице WITHOUT ROWID значение шестого параметра не определена. Для INSERT или UPDATE на таблице rowid седьмой параметр указывает финальное значение rowid строки, вставляемой или обновленной. Значение седьмого параметра, переданного к функции обратного вызова, не определяется для операций на таблицах WITHOUT ROWID или для DELETE на таблицах rowid.

sqlite3_preupdate_hook(D,C,P) возвращает аргумент P от предыдущего запроса к тому же самому соединению с базой данных D или NULL для первого запроса на D.

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

sqlite3_preupdate_count(D) возвращает количество колонок в строке, которые вставляются, обновляются или удаляются.

sqlite3_preupdate_old(D,N,P) пишет в P указатель на protected sqlite3_value, который содержит значение столбца N строки таблицы, прежде чем это будет обновлено. Параметр N должен быть между 0 и меньше, чем количество колонок, или поведение будет не определено. Это должно использоваться только в SQLITE_UPDATE и SQLITE_DELETE, если это используется отзывом SQLITE_INSERT, поведение не определено. sqlite3_value, на который указывает P, будет разрушен, когда отзыв перед обновлением возвратит значение.

sqlite3_preupdate_new(D,N,P) пишет в P указатель на protected sqlite3_value, который содержит значение столбца N строки таблицы после того, как это обновляется. Параметр N должен быть между 0 и меньше, чем количество колонок, или поведение будет не определено. Это должно использоваться только в отзывах SQLITE_INSERT и SQLITE_UPDATE, если это используется отзывом SQLITE_DELETE, поведение не определено. sqlite3_value, на который указывает P, будет разрушен, когда отзыв перед обновлением возвратит значение.

sqlite3_preupdate_depth(D) вернет 0, если отзыв перед обновлением был вызван в результате прямой вставки, обновления или удаления, 1 для вставок, обновлений или удалений, вызванных триггерами верхнего уровня, 2 для вставок, обновлений или удалений, вызванных триггерами второго уровня и т. д.

Когда sqlite3_blob_write() API используется, чтобы обновить колонку blob, перехват перед обновлением вызван с SQLITE_DELETE. Это вызвано тем, что в этом случае новые значения недоступны. В этом случае, когда отзыв, сделанный с op==SQLITE_DELETE, на самом деле пишет через sqlite3_blob_write() API, sqlite3_preupdate_blobwrite() возвращает индекс написанной колонки. В других случаях, где перехват перед обновлением вызывается по некоторой другой причине, включая регулярный DELETE, sqlite3_preupdate_blobwrite() вернет -1.

См. также: sqlite3_update_hook().

---

Отслеживание и профилирование функций

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,
                      sqlite3_uint64), void*);

Это регистрирует функции обратного вызова, которые могут использоваться для отслеживания и профилирования выполнения SQL-операторов.

Функция обратного вызова, зарегистрированная sqlite3_trace(), вызвана неоднократно, когда SQL-оператором управляет sqlite3_step(). sqlite3_trace() вызван с предоставлением UTF-8 текста SQL-оператора, когда запрос начинает выполняться. Дополнительные отзывы sqlite3_trace() могли бы произойти, когда каждая вызванная подпрограмма введена. Отзывы для триггеров содержат UTF-8 SQL-комментарий, который определяет триггер.

Опция SQLITE_TRACE_SIZE_LIMIT может использоваться, чтобы ограничить длину связанного параметра в выводе sqlite3_trace().

Функция обратного вызова, зарегистрированная sqlite3_profile(), вызвана, когда каждый SQL-оператор заканчивается. Отзыв профиля содержит оригинальный текст инструкции и оценку времени выполнения в наносекундах. Время отзыва профиля находится в единицах наносекунд, однако текущее внедрение способно только к точности миллисекунды, таким образом, шесть младших значащих цифр бессмысленны. Будущие версии SQLite могли бы предоставить большую точность по отзыву профилировщика. Вызов sqlite3_trace() или sqlite3_trace_v2() отменит отзыв профиля.

---

Урегулирование результата функции SQL

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_blob64(sqlite3_context*,const void*,
                           sqlite3_uint64,void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
                           void(*)(void*), unsigned char encoding);
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
void sqlite3_result_zeroblob(sqlite3_context*, int n);
int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);

Это используется отзывами xFunc или xFinal, которые осуществляют функции SQL и совокупности. См. sqlite3_create_function() и sqlite3_create_function16().

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

sqlite3_result_blob() устанавливает результат определенной приложением функции в BLOB, на содержание которого указывает второй параметр и который является N байтами, где N это третий параметр.

sqlite3_result_zeroblob(C,N) и sqlite3_result_zeroblob64(C,N) устанавливают результат определенной применением функции в BLOB, содержащий все нулевые байты и N байт в размере.

sqlite3_result_double() устанавливает результат определенной применением функции в значение с плавающей точкой, определенное его 2-м аргументом.

sqlite3_result_error() и sqlite3_result_error16() заставляют осуществленную функцию SQL бросать исключение. SQLite использует последовательность, на которую указывает 2-й параметр sqlite3_result_error() или sqlite3_result_error16() как текст сообщения об ошибке. SQLite интерпретирует последовательность сообщения об ошибке от sqlite3_result_error() как UTF-8. SQLite интерпретирует последовательность от sqlite3_result_error16() как UTF-16 с использованием тех же самых правил определения порядка байтов как sqlite3_bind_text16(). Если третий параметр sqlite3_result_error() или sqlite3_result_error16() отрицателен, SQLite берет в качестве сообщения об ошибке весь текст до первого нулевого символа. Если третий параметр sqlite3_result_error() или sqlite3_result_error16() неотрицательный, SQLite берет это число байтов (не знаков) от 2-го параметра как сообщение об ошибке. sqlite3_result_error() и sqlite3_result_error16() делает частную копию текста сообщения об ошибке, прежде чем они возвратятся. Следовательно, функция запроса может освободить или изменить текст после того, как они возвратятся без вреда. Функция sqlite3_result_error_code() изменяет код ошибки, возвращенный SQLite в результате ошибки в функции. По умолчанию код ошибки SQLITE_ERROR. Последующий запрос sqlite3_result_error() или sqlite3_result_error16() перезагружает код ошибки к SQLITE_ERROR.

sqlite3_result_error_toobig() заставляет SQLite бросать ошибку при указании, что последовательность или BLOB слишком длинные.

sqlite3_result_error_nomem() заставляет SQLite бросать ошибку при указании, что выделение памяти потерпело неудачу.

sqlite3_result_int() устанавливает возвращаемое значение определенной применением функции в 32-bit signed integer, данном во 2-м аргументе. sqlite3_result_int64() устанавливает возвращаемое значение определенной применением функции в 64-bit signed integer, данном во 2-м аргументе.

sqlite3_result_null() устанавливает возвращаемое значение определенной применением функции в NULL.

sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le() и sqlite3_result_text16be() устанавливают возвращаемое значение определенной применением функции в текстовую строку, которая представляется как UTF-8, родной порядок байтов UTF-16, прямой порядок байтов UTF-16 или обратный порядок байтов UTF-16, соответственно. sqlite3_result_text64() устанавливает возвращаемое значение определенной применением функции в текстовую строку в кодировании, определенном пятым (и последним) параметром, который должен быть одним из SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE. SQLite берет текстовый результат из второго параметра sqlite3_result_text*. Если 3-й параметр к какому-либо из sqlite3_result_text*, кроме sqlite3_result_text64(), отрицательный, то SQLite вычисляет длину строки, ища во 2-й параметре первый нулевой символ. Если 3-й параметр sqlite3_result_text* неотрицательный, то соответствующее число байтов (не знаков) текста, на который указывает 2-й параметр, взяты в качестве определенного применением результата функции. Если 3-й параметр неотрицательный, то это должно быть байтовое смещение в последовательность, где терминатор NUL появится, если строка заканчивается NUL. Если какие-либо знаки NUL есть в последовательности при байтовом смещении, которое меньше, чем значение 3-го параметра, то получившаяся строка будет содержать включенный NUL, и результат выражений, воздействующих на последовательности с вложенным NUL, не определен. Если 4-й параметр sqlite3_result_text* или sqlite3_result_blob не NULL, SQLite вызывает ту функцию как деструктор на тексте или результате BLOB, когда это закончило использовать тот результат. Если 4-й параметр sqlite3_result_text* или sqlite3_result_blob является специальным постоянным SQLITE_STATIC, SQLite предполагает, что результат текста или BLOB находится в постоянном месте и не копирует содержание параметра, а также не вызывает деструктор на содержании, когда это закончило использовать результат. Если 4-й параметр sqlite3_result_text* или sqlite3_result_blob является константой SQLITE_TRANSIENT, SQLite делает копию результата в место, получнное из sqlite3_malloc().

Для sqlite3_result_text16(), sqlite3_result_text16le() и sqlite3_result_text16be() и для sqlite3_result_text64(), когда кодирование не UTF8, если вход UTF16 начинается с отметки порядка байтов (BOM, U+FEFF), BOM удален из последовательности, и остальная часть последовательности интерпретируется согласно порядку байтов, определенному BOM. Порядок байтов, определенный BOM в начале текста, отвергает порядок байтов, определенный интерфейсной процедурой. Так, например, если sqlite3_result_text16le() вызван с текстом, который начинается с байтов 0xfe, 0xff (отметка обратного порядка байтов), тогда первые два байта входа пропускаются, и остающийся вход интерпретируется как текст UTF16BE.

Для входного текста UTF16 в sqlite3_result_text16(), sqlite3_result_text16be(), sqlite3_result_text16le() и sqlite3_result_text64(), если текст содержит недействительные знаки UTF16, недопустимые символы могли бы быть преобразованы в unicode-символ замены, U+FFFD.

sqlite3_result_value() устанавливает результат определенной применением функции в копию объекта unprotected sqlite3_value, определенного 2-м параметром. sqlite3_result_value() делает копию sqlite3_value так, чтобы sqlite3_value, определенный в параметре, мог измениться или быть освобожден после возврата sqlite3_result_value(). Объект protected sqlite3_value может всегда использоваться, где нужен объект unprotected sqlite3_value, таким образом, любой вид объекта sqlite3_value может использоваться с этим интерфейсом.

sqlite3_result_pointer(C,P,T,D) устанавливает результат в SQL NULL, точно так же, как sqlite3_result_null(C), за исключением того, что это также связывает указатель базового языка P или тип T с NULL таким образом, что указатель может быть получен в определенной функции SQL через sqlite3_value_pointer(). Если D не NULL, то это указатель на деструктор для параметра P. SQLite вызывает D с P как его единственный аргумент, когда SQLite закончит с P. Параметр T должен быть статической последовательностью и предпочтительно строковым литералом. sqlite3_result_pointer() является частью интерфейса прохождения указателя, добавленного в SQLite 3.20.0.

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

---

Динамический статус SQLite

int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
int sqlite3_status64(int op, sqlite3_int64 *pCurrent,
                     sqlite3_int64 *pHighwater, int resetFlag);

Эти интерфейсы используются, чтобы получить информацию о динамическом статусе исполнения SQLite и произвольно перезагрузить различные высшие точки. Первый аргумент это код целого числа для определенного параметра, чтобы указать размеры. Признанные коды целого числа имеют форму SQLITE_STATUS_.... Текущее значение параметра возвращено в *pCurrent. Самое высокое зарегистрированное значение возвращено в *pHighwater. Если resetFlag = true, то самое высокое рекордное значение перезагружается после записи в *pHighwater. Некоторые параметры не делают запись самого высокого значения. Для тех параметров в *pHighwater ничего не пишется и игнорируется resetFlag. Другие параметры делают запись только высшей точки, а не текущего значения. Для этих последних параметров ничего не пишется в *pCurrent.

sqlite3_status() и sqlite3_status64() вернут SQLITE_OK при успехе и ненулевой код ошибки при сбое.

Если текущее значение или высшая точка слишком большие, чтобы быть представленными 32-битным целым числом, то значения, возвращенные sqlite3_status() не определены.

См. также: sqlite3_db_status().

---

Подготовленный статус просмотра запроса

int sqlite3_stmt_scanstatus(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  void *pOut                /* Result written here */
);
int sqlite3_stmt_scanstatus_v2(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  int flags,                /* Mask of flags defined below */
  void *pOut                /* Result written here */
);

Эти интерфейсы возвращают информацию о предсказанном и измеренном уровне для pStmt. Усовершенствованные приложения могут использовать этот интерфейс, чтобы сравнить предсказанный и измеренный уровень для предупреждения проблемы и/или запустить повторно ANALYZE, если несоответствия найдены.

Так как этот интерфейс, как ожидают, будет редко использоваться, это доступно только, если SQLite собран, используя выбор времени компиляции SQLITE_ENABLE_STMT_SCANSTATUS.

"iScanStatusOp" определяет, какую информацию о статусе возвратить. "iScanStatusOp" должен быть одним из вариантов scanstatus или поведение этого интерфейса не определено. Требуемое измерение написано в переменную, на которую указывает параметр "pOut".

"flags" должен быть передан как маска флагов. В настоящее время только один флаг определяется SQLITE_SCANSTAT_COMPLEX. Если указан SQLITE_SCANSTAT_COMPLEX, информация о статусе доступна для всех элементов плана запросов, о которых сообщает "EXPLAIN QUERY PLAN". Если не указан SQLITE_SCANSTAT_COMPLEX, то только элементы плана запросов, которые соответствуют циклам запроса (элементам "SCAN..." и "SEARCH..." в выводе EXPLAIN QUERY PLAN), доступны. Вызов API sqlite3_stmt_scanstatus() эквивалентен запросу sqlite3_stmt_scanstatus_v2() с обнуленным параметром флагов.

"idx" определяет определенный элемент запроса, чтобы получить статистику для него. Элементы запроса пронумерованы с 0. Значение -1 нужно для запроса статистики относительно всего запроса. Если idx вне диапазона (меньше -1 или больше, чем или равно общему количеству элементов запроса) ненулевое значение возвращено и переменная, указанная pOut, не изменена.

См. также: sqlite3_stmt_scanstatus_reset().

---

Добавьте содержание к динамической последовательности

void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
void sqlite3_str_reset(sqlite3_str*);

Эти интерфейсы добавляют содержание к объекту sqlite3_str, ранее полученному из sqlite3_str_new().

sqlite3_str_appendf(X,F,...) и sqlite3_str_vappendf(X,F,V) используют встроенный printf SQLite, чтобы добавить форматированный текст в конец объекта sqlite3_str X.

Метод sqlite3_str_append(X,S,N) добавляет точно N байт последовательности S в конец объекта sqlite3_str X. N должен быть неотрицательным. S должен содержать по крайней мере N байт, отличных от нуля. Чтобы добавить законченную нолем последовательность в целом, используйте метод sqlite3_str_appendall().

Метод sqlite3_str_appendall(X,S) добавляет полное содержание законченной нолем последовательности S в конец объекта sqlite3_str X.

Метод sqlite3_str_appendchar(X,N,C) добавляет N копий однобайтового символа C в конец объекта sqlite3_str X. Этот метод может использоваться, например, чтобы добавить пробелы.

Метод sqlite3_str_reset(X) перезагружает последовательность в процессе строительства в объекте sqlite3_str X к длине в 0 байт.

Эти методы не возвращают код результата. Если ошибка происходит, тот факт зарегистрирован в объекте sqlite3_str и может быть получен через sqlite3_str_errcode(X).

---

Статус динамической последовательности

int sqlite3_str_errcode(sqlite3_str*);
int sqlite3_str_length(sqlite3_str*);
char *sqlite3_str_value(sqlite3_str*);

Эти интерфейсы возвращают текущий статус объекта sqlite3_str.

Если какие-либо предшествующие ошибки произошли, строя динамическую последовательность в sqlite3_str X, метод sqlite3_str_errcode(X) возвратит соответствующий код ошибки. Метод sqlite3_str_errcode(X) вернет SQLITE_NOMEM после любой ошибки памяти, SQLITE_TOOBIG, если размер динамической последовательности превышает SQLITE_MAX_LENGTH, или SQLITE_OK, если все в порядке.

Метод sqlite3_str_length(X) возвращает текущую длину в байтах динамической последовательности в процессе строительства в объекте sqlite3_str X. Длина, возвращенная sqlite3_str_length(X), не включает байт нулевого завершения.

Метод sqlite3_str_value(X) возвращает указатель на текущее содержание динамической последовательности в процессе строительства в X. Значение, возвращенное sqlite3_str_value(X), управляет объектом sqlite3_str X и может быть освобождено или изменено любым последующим методом на том же самом объекте sqlite3_str. Запросы не должны использовать указатель, возвращенный sqlite3_str_value(X), после любого последующего вызова метода на том же самом объекте. Запросы могут изменить содержание последовательности, возвращенной sqlite3_str_value(X), пока они не пишут ни в какие байты вне диапазона от 0 до sqlite3_str_length(X) и не читают или пишут любой байт после любого последующего вызова метода sqlite3_str.

---

Сравнение строк

int sqlite3_stricmp(const char *, const char *);
int sqlite3_strnicmp(const char *, const char *, int);

sqlite3_stricmp() и sqlite3_strnicmp() API позволяет сравнивать содержание двух буферов, содержащих последовательности UTF-8 независимо от регистра, используя то же самое определение "case independence", которое SQLite использует внутренне, сравнивая идентификаторы.

---

Общее количество измененных строк

int sqlite3_total_changes(sqlite3*);
sqlite3_int64 sqlite3_total_changes64(sqlite3*);

Эти функции возвращают общее количество строк, вставленных, измененных или удаленных всеми INSERT, UPDATE или DELETE с момента, когда соединение с базой данных было открыто, включая выполненные как часть триггеров. Две функции идентичны за исключением типа возвращаемого значения и того что, если количество строк, измененных связью, превышает максимальное значение, поддержанное типом "int", возвращаемое значение sqlite3_total_changes() не определено. Выполнение любого другого типа SQL-оператора не затрагивает значение, возвращенное sqlite3_total_changes().

Изменения, внесенные как часть действий внешнего ключа, включены в количество, но сделанные как часть ограничительной резолюции REPLACE не включены. Изменения представления, которые перехвачены триггерами INSTEAD OF, не посчитаны.

sqlite3_total_changes(D) сообщает только о количестве строк, которые изменились из-за SQL-оператора, которым управляют для соединения с базой данных D. Любые изменения другими соединениями с базой данных проигнорированы. Чтобы обнаружить изменения файла базы данных от других соединений с базой данных используют PRAGMA data_version или SQLITE_FCNTL_DATA_VERSION file control.

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

---

Получите значения для параметров URI

const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
const char *sqlite3_uri_key(sqlite3_filename z, int N);

Это сервисная процедура, полезная для реализации VFS, а именно для проверки, если файлом базы данных был URI, который содержал определенный параметр запроса, и если так, то получения значения того параметра запроса.

Первый параметр к этим интерфейсам (в дальнейшем именуемый F) должен быть одним из:

• Указатель имени файла базы данных, созданный ядром SQLite и переданный в метод xOpen() внедрения VFS
• Имя файла из sqlite3_db_filename()
• Новое имя файла, построенное с использованием sqlite3_create_filename().

Если параметр F не один из вышеупомянутых, то поведение не определено и вероятно нежелательно. Более старые версии SQLite были более терпимы к недействительным параметрам F, чем более новые версии.

Если F подходящее имя файла (как описано в предыдущем параграфе) и P название параметра запроса, то sqlite3_uri_parameter(F,P) вернет значение параметра P, если это существует или NULL, если P не появляется как параметр запроса в F. Если P параметр запроса F, и у этого нет явного значения, sqlite3_uri_parameter(F,P) вернет указатель на пустую строку.

sqlite3_uri_boolean(F,P,B) предполагает, что P булев параметр и возвращает true (1) или false (0), согласно значению P. sqlite3_uri_boolean(F,P,B) вернет true (1), если значение параметра запроса P является одним из "yes", "true" или "on" в любом регистре или если значение начинается с числа, отличного от нуля. sqlite3_uri_boolean(F,P,B) вернет false (0), если значение параметра запроса P является одним из "no", "false" или "off" в любом регистре или если значение начинается с 0. Если P не параметр запроса на F или если значение P не соответствует ни одному из вышеупомянутых вариантов, то sqlite3_uri_boolean(F,P,B) вернет (B!=0).

sqlite3_uri_int64(F,P,D) преобразовывает значение P в 64-битное целое число со знаком и вернет это целое число или D, если P не существует. Если значение P что-то другое, чем целое число, то ноль возвращен.

sqlite3_uri_key(F,N) возвращает указатель на имя (не значение) параметра N запроса для имени файла F или NULL, если N меньше ноля или больше, чем количество параметров запроса минус 1. Значение N основано на ноле, таким образом, N должен быть 0, чтобы получить название первого параметра запроса, 1 для второго параметра и т.д.

Если F = NULL, sqlite3_uri_parameter(F,P) вернет NULL, sqlite3_uri_boolean(F,P,B) вернет B. Если F не NULL и не является указателем пути файла базы данных, который ядро SQLite передало в метод xOpen VFS, то поведение этой функции не определено и вероятно нежелательно.

Начиная с SQLite version 3.31.0 (2020-01-22) параметр F может также быть названием файла журнала обратной перемотки или файла WAL в дополнение к главному файлу базы данных. До версии 3.31.0 это работало только если F был названием главного файла базы данных. Когда параметр F название журнала обратной перемотки или файла WAL, у этого есть доступ ко всем одинаковым параметрам запроса, какие были для главного файла базы данных.

---

Получение значения SQL

const void *sqlite3_value_blob(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
void *sqlite3_value_pointer(sqlite3_value*, const char*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
const void *sqlite3_value_text16be(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);
int sqlite3_value_nochange(sqlite3_value*);
int sqlite3_value_frombind(sqlite3_value*);

Обзор:

sqlite3_value_blob	→	BLOB
sqlite3_value_double	→	REAL
sqlite3_value_int	→	32-bit INTEGER
sqlite3_value_int64	→	64-bit INTEGER
sqlite3_value_pointer	→	Указатель
sqlite3_value_text	→	UTF-8 TEXT
sqlite3_value_text16	→	UTF-16 TEXT в нативном порядке байт
sqlite3_value_text16be	→	UTF-16be TEXT
sqlite3_value_text16le	→	UTF-16le TEXT
sqlite3_value_bytes	→	Размер BLOB или текста UTF-8 TEXT в байтах
sqlite3_value_bytes16	→	Размер UTF-16 TEXT в байтах
sqlite3_value_type	→	Значение по умолчанию для этого типа данных
sqlite3_value_numeric_type	→	Лучше всего подходящий значению числовой тип данных
sqlite3_value_nochange	→	True, если колонка неизменна в UPDATE для виртуальной таблицы.
sqlite3_value_frombind	→	True, если значение порождено из связанного параметра

Детали:

Это извлекает тип, размер и информацию о содержании из объектов protected sqlite3_value. Они используются, чтобы передать информацию о параметре в функции, которые осуществляют функции SQL и виртуальные таблицы.

Это работает только с объектами protected sqlite3_value. Любая попытка использовать это на unprotected sqlite3_value не ориентирована на многопоточное исполнение.

Это работает точно так же, как соответствующие функции доступа колонки за исключением того, что эта хранимая процедура берет один объект protected sqlite3_value вместо указателя sqlite3_stmt* и номер столбца целого числа.

sqlite3_value_text16() извлекает последовательность UTF-16 в родном порядке байтов хост-машины. sqlite3_value_text16be() и sqlite3_value_text16le() извлекают последовательности UTF-16 как в прямом порядке байтов, так и в обратном соответственно.

Если объект sqlite3_value V был инициализирован, используя sqlite3_bind_pointer(S,I,P,X,D) или sqlite3_result_pointer(C,P,X,D) и если X и Y это последовательности, которые выдерживают сравнение равенства через strcmp(X,Y), sqlite3_value_pointer(V,Y) вернет указатель P. Иначе sqlite3_value_pointer(V,Y) вернет NULL. sqlite3_bind_pointer() является частью интерфейса прохождения указателя, добавленного в SQLite 3.20.0.

sqlite3_value_type(V) возвращает код типа данных для начального типа данных объекта sqlite3_value V. Возвращенное значение одно из SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB или SQLITE_NULL. Другие интерфейсы могли бы изменить тип данных для объекта sqlite3_value. Например, если тип данных первоначально SQLITE_INTEGER и sqlite3_value_text(V) вызывают, чтобы извлечь текстовое значение для того целого числа, то последующие sqlite3_value_type(V) могут вернуть SQLITE_TEXT. Происходит ли постоянное внутреннее преобразование типа данных, не определено и может измениться от одного выпуска SQLite к следующему.

sqlite3_value_numeric_type() пытается применить числовую близость к значению. Это означает, что попытка предпринята, чтобы преобразовать значение в целое число или число с плавающей точкой. Если такое преобразование возможно без потери информации (другими словами, если значение это последовательность, которая похожа на число), преобразование выполняется. Иначе никакое преобразование не происходит. datatype после преобразования возвращен.

В методе xUpdate виртуальной таблицы sqlite3_value_nochange(X) вернет true если и только если колонка, соответствующая X, неизменна операцией UPDATE, которую вызов метода xUpdate был вызван осуществить и если предшествующий вызов метода xColumn, который был вызван для извлечения значения для той колонки, не установил результат (вероятно, потому что это запросило sqlite3_vtab_nochange() и нашло, что колонка была неизменна). В рамках метода xUpdate любое значение, для которого sqlite3_value_nochange(X) = true, во всех других отношениях NULL. Если sqlite3_value_nochange(X) вызван где-нибудь кроме xUpdate, то возвращаемое значение произвольно и бессмысленно.

sqlite3_value_frombind(X) вернет не 0, если значение X порождено из одного из sqlite3_bind(). Если X прибывает из литерального значения SQL, столбца таблицы или выражения, то sqlite3_value_frombind(X) вернет 0.

Пожалуйста, обратите особое внимание на то, что указатель, возвращенный из sqlite3_value_blob(), sqlite3_value_text() или sqlite3_value_text16(), может быть лишен законной силы последующим запросом sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text() или sqlite3_value_text16().

Это нужно вызвать от того же самого потока, как функция SQL, которая поставляла параметры sqlite3_value*.

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

• sqlite3_value_blob()
• sqlite3_value_text()
• sqlite3_value_text16()
• sqlite3_value_text16le()
• sqlite3_value_text16be()
• sqlite3_value_bytes()
• sqlite3_value_bytes16()

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

---

Копия и освобождение значений SQL

sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
void sqlite3_value_free(sqlite3_value*);

sqlite3_value_dup(V) делает копию sqlite3_value объекта D и возвращает указатель на ту копию. Возвращенный sqlite3_value объект это protected sqlite3_value даже если вход им не был. sqlite3_value_dup(V) вернет NULL, если V = NULL или выделение памяти терпит неудачу. Если V указатель, то результатом sqlite3_value_dup(V) будет NULL.

sqlite3_value_free(V) освобождает объект sqlite3_value, ранее полученный из sqlite3_value_dup(). Если V = NULL, то sqlite3_value_free(V) ничего не делает.

---

Объекты виртуальной файловой системы

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
int sqlite3_vfs_unregister(sqlite3_vfs*);

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

sqlite3_vfs_find() возвращает указатель на VFS, заданный его именем. Имена чувствительные к регистру. Имена это законченные нолем последовательности UTF-8. Если это не выполняется, NULL возвращен. Если zVfsName = NULL, VFS по умолчанию возвращен.

Новые VFS зарегистрированы sqlite3_vfs_register(). Каждый новый VFS становится умолчанием VFS, если установлен флаг makeDflt. Тот же самый VFS может быть зарегистрирован многократно без проблем. Чтобы превратить существующий VFS в умолчание VFS, зарегистрируйте его снова с установленным флагом makeDflt. Если два различных VFS с тем же самым именем зарегистрированы, поведение не определено. Если VFS зарегистрирован с именем, которое NULL или пустая строка, то поведение не определено.

Снятие регистрации VFS делается через sqlite3_vfs_unregister(). Если VFS по умолчанию снят с регистрации, другой VFS выбран в качестве умолчания. Выбор для нового VFS произволен.

---

Найдите все элементы на правой стороне ограничения IN

int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);

Эти интерфейсы полезны только в методе xFilter() виртуальной таблицы. Результат вызова этих интерфейсов от любого другого контекста не определен и вероятно вреден.

Параметр X в вызове sqlite3_vtab_in_first(X,P) или sqlite3_vtab_in_next(X,P) должны быть одним из параметров метода xFilter, который вызывает эту хранимую процедуру, и определенно параметр, который был ранее отобран для ограничительного использования обработки IN sqlite3_vtab_in() в методе xBestIndex. Если параметр X не аргумент xFilter, который был отобран для ограничительной обработки IN, то это возвращает SQLITE_ERROR.

Используйте это, чтобы получить доступ ко всем значениям на правой стороне ограничения IN, используя такой код:

   for (rc=sqlite3_vtab_in_first(pList, &pVal);
        rc==SQLITE_OK && pVal;
        rc=sqlite3_vtab_in_next(pList, &pVal)
   ) {
     // do something with pVal
   }
   if (rc!=SQLITE_OK) {
      // an error has occurred
   }

При успехе sqlite3_vtab_in_first(X,P) и sqlite3_vtab_in_next(X,P) вернут SQLITE_OK и установят *P, чтобы указывать на первое или следующее значение RHS в ограничении IN. Если больше нет значений на правой стороне ограничения IN, то *P установлен в NULL, и это возвращает SQLITE_DONE. Возвращаемое значение могло бы быть некоторым другим значением, таким как SQLITE_NOMEM, в случае сбоя.

Значения *ppOut, возвращенные этой функцией, действительны только до следующего вызова этой функции или до конца метода xFilter, из которого вызвали эту функцию. Если виртуальное внедрение таблицы должно сохранить значения *ppOut дольше, оно должно сделать копии. Значения *ppOut protected.

---

Win32-определенный интерфейс

int sqlite3_win32_set_directory(
  unsigned long type, /* Identifier for directory being set or reset */
  void *zValue        /* New value for directory being set or reset */
);
int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);

Эти интерфейсы доступны только на Windows. Интерфейс sqlite3_win32_set_directory используется, чтобы установить значение, связанное с переменной sqlite3_temp_directory или sqlite3_data_directory, в zValue, в зависимости от значения параметра типа. Параметр zValue должен быть NULL, чтобы заставить предыдущее значение быть освобожденным через sqlite3_free, не NULL будет скопировано в память, полученную из sqlite3_malloc. Интерфейс sqlite3_win32_set_directory вернет SQLITE_OK, чтобы указать на успех, SQLITE_ERROR, если тип не поддерживается или SQLITE_NOMEM, если память не могла быть ассигнована. Значение переменной sqlite3_data_directory предназначается, чтобы действовать как замена для текущего каталога на подплатформах Win32, где то понятие не присутствует, например, WinRT и UWP. sqlite3_win32_set_directory8 и sqlite3_win32_set_directory16 ведут себя точно так же, как sqlite3_win32_set_directory, кроме строкового параметра должен быть UTF-8 или UTF-16, соответственно.

---

Закрепление значений к подготовленным запросам

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
                        void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
                         void(*)(void*), unsigned char encoding);
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,
                         void(*)(void*));
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);

Во вводе текста SQL-оператора в sqlite3_prepare_v2() и его вариантах литералы могут быть заменены параметром, который соответствует одному из следующих шаблонов:

• ?
• ?NNN
• :VVV
• @VVV
• $VVV

В шаблонах выше NNN представляет буквальное целое число, а VVV представляет алфавитно-цифровой идентификатор. Значения этих параметров (также названных "названия параметра хоста" или "параметры SQL") могут быть установлены, используя sqlite3_bind_*().

Первым аргументом sqlite3_bind_*() всегда является указатель на объект sqlite3_stmt, возвращенный из sqlite3_prepare_v2() или его вариантов.

Второй аргумент это индекс параметра SQL, который будет установлен. У крайнего левого параметра SQL есть индекс 1. Когда тот же самый названный параметр SQL используется несколько раз, у вторых и последующих случаев есть тот же самый индекс, как первое возникновение. Индекс для названных параметров может искаться, используя sqlite3_bind_parameter_index() API. Индекс для параметров "?NNN" является значением NNN. Значение NNN должно быть между 1 и sqlite3_limit(), параметр SQLITE_LIMIT_VARIABLE_NUMBER (по умолчанию: 32766).

Третий аргумент это значение, чтобы связать с параметром. Если третий параметр sqlite3_bind_text(), sqlite3_bind_text16() или sqlite3_bind_blob() это NULL, четвертый параметр проигнорирован, и конечный результат совпадает с sqlite3_bind_null(). Если третьим параметром sqlite3_bind_text() не является NULL, то это должен быть указатель на правильно построенный текст UTF8. Если третьим параметром sqlite3_bind_text16() не является NULL, то это должен быть указатель на правильно построенный текст UTF16. Если третьим параметром sqlite3_bind_text64() не является NULL, то это должен быть указатель на правильно построенную последовательность unicode, которая является UTF8, если шестой параметр SQLITE_UTF8, или UTF16 иначе.

Порядок байтов входного текста UTF16 определяется отметкой порядка байтов (BOM, U+FEFF) в первом символе, который удален, в отсутствие BOM порядок байтов это родной порядок байтов хост-машины для sqlite3_bind_text16() или порядок байтов, определенный в 6-м параметре для sqlite3_bind_text64(). Если входной текст UTF16 содержит недействительные unicode знаки, то SQLite мог бы изменить те недопустимые символы в unicode-символ замены: U+FFFD.

В том установленном порядке, у которого есть четвертый аргумент, его значение это число байтов в параметре. Значение это число байт в значении, а не количество знаков. Если четвертый параметр sqlite3_bind_text() или sqlite3_bind_text16() отрицателен, то длина последовательности это число байтов до первого нулевого терминатора. Если четвертый параметр sqlite3_bind_blob() отрицателен, то поведение не определено. Если неотрицательный четвертый параметр предоставляется sqlite3_bind_text(), sqlite3_bind_text16() или sqlite3_bind_text64(), этот параметр должен быть байтовым смещением, где терминатор NUL произошел бы, предположив, что последовательность была закончена NUL. Если какие-либо знаки NUL есть при байтовых смещениях меньше, чем значение четвертого параметра, то значение получившей строки будет содержать включенный NUL. Результат выражений, связавших последовательности с вложенным NUL, не определен.

Пятый аргумент BLOB и интерфейсам привязки последовательности управляет или указывает на целую жизнь объекта, на который ссылается третий параметр. Эти три варианта существуют: (1) деструктор А, чтобы избавиться от BLOB или последовательности после завершения работы с ним. Это вызывают, чтобы избавиться от BLOB или последовательности, даже если запрос к API терпит неудачу, кроме вызова деструктора, если третий параметр это NULL или четвертый параметр отрицателен. (2) Специальная константа SQLITE_STATIC может быть передана, чтобы указать, что применение остается ответственным за избавление от объекта. В этом случае объект и обеспеченный указатель на него должны остаться действительными, пока подготовленный запрос не завершен или тот же самый параметр SQL, связан с чем-то еще. (3) Константа SQLITE_TRANSIENT может быть передана, чтобы указать, что объект должен быть скопирован до возвращения из sqlite3_bind_*(). Объект и указатель на него должны остаться действительными до тех пор. SQLite будет тогда управлять целой жизнью своей частной копии.

Шестым аргументом sqlite3_bind_text64() должен быть один из SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE, чтобы определить кодирование текста в третьем параметре. Если шестым аргументом sqlite3_bind_text64() не является одно из позволенных значений, показанных выше, или если текстовое кодирование отличается от кодирования, определенного шестым параметром, то поведение не определено.

sqlite3_bind_zeroblob() привязывает BLOB длиной N, который заполнен нолями. Здесь zeroblob использует установленную сумму памяти (просто целое число, чтобы хранить его размер), в то время как это обрабатывается. Zeroblob предназначаются, чтобы служить заполнителями для BLOB, содержание которых позже написано, используя возрастающий BLOB I/O. Отрицательная величина для zeroblob приводит к нулевой длине BLOB.

sqlite3_bind_pointer(S,I,P,T,D) заставляет параметр I в подготовленном запросе S иметь значение SQL NULL, но также быть связанным с указателем P типа T. D это NULL или указатель на функцию деструктора для P. SQLite вызовет деструктор D с отдельным аргументом P, когда это закончит использование P. Параметр T должен быть статической последовательностью, предпочтительно строковый литерал. sqlite3_bind_pointer() является частью интерфейса прохождения указателя, добавленного в SQLite 3.20.0.

Если любой из sqlite3_bind_*() вызовут с NULL для подготовленного запроса или с подготовленным запросом0, для которого sqlite3_step() вызвали позже, чем sqlite3_reset(), то запрос возвратит SQLITE_MISUSE. Если любому sqlite3_bind_() передается подготовленный запрос, который был завершен, результат не определен и вероятно вреден.

Привязки не очищены sqlite3_reset(). Несвязанные параметры интерпретируются как NULL.

sqlite3_bind_* вернет SQLITE_OK при успехе или код ошибки, если что-нибудь идет не так, как надо. SQLITE_TOOBIG мог бы быть возвращен, если размер последовательности или BLOB превышает ограничения sqlite3_limit( SQLITE_LIMIT_LENGTH) или SQLITE_MAX_LENGTH. SQLITE_RANGE возвращен, если индекс параметра вне диапазона. SQLITE_NOMEM возвращен, если malloc() провалился.

См. также: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name() и sqlite3_bind_parameter_index().

---

Компилирование SQL-оператора

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v3(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v3(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

Чтобы выполнить SQL-оператор, это должно сначала быть собрано в программу байт-код, используя одну из этих функций. Или другими словами эти хранимые процедуры это конструкторы для объекта подготовленного запроса.

Предпочтительная процедура, чтобы использовать, это sqlite3_prepare_v2(). Интерфейс sqlite3_prepare() устарел и лучше его не трогать. sqlite3_prepare_v3() имеет дополнительный параметр "prepFlags", который используется для особых целей.

Использование интерфейсов UTF-8 предпочтено, поскольку SQLite в настоящее время делает весь парсинг, используя UTF-8. Интерфейсы UTF-16 обеспечиваются как удобство. UTF-16 соединяет работу, преобразовывая входной текст в UTF-8, затем вызывая соответствующий интерфейс UTF-8.

Первым аргументом, "db", является соединение с базой данных, полученное от предшествующего успешного вызова sqlite3_open(), sqlite3_open_v2() или sqlite3_open16(). Соединение с базой данных не должно быть закрыто.

Вторым аргументом, "zSql", является запрос для сборки, закодированный как UTF-8 или UTF-16. sqlite3_prepare(), sqlite3_prepare_v2() и sqlite3_prepare_v3() используют UTF-8, а sqlite3_prepare16(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() используют UTF-16.

Если nByte отрицателен, zSql прочитан до первого нулевого терминатора. Если nByte положительный, то это число байтов, прочитанных из zSql. Если nByte = 0, то никакой подготовленный запрос не произведен. Если вызывающий знает, что предоставленная строка nul-закончена, то есть небольшое исполнительное преимущество для прохождения nByte параметра, который является числом байтов во входной строке включая nul-терминатор.

Если pzTail не NULL, *pzTail указывает на первый байт после конца первого SQL-оператора в zSql. Эта хранимая процедура только собирает первый запрос в zSql, таким образом, *pzTail указывает налево к тому, что остается несобранным.

*ppStmt указывает налево к собранному подготовленному запросу, который может быть выполнен, используя sqlite3_step(). Если есть ошибка, *ppStmt установлен в NULL. Если входной текст не содержит SQL (если вход пустая строка или комментарий), тогда *ppStmt = NULL. Процедура запроса ответственна за удаление собранного SQL-оператора, используя sqlite3_finalize() после того, как это закончило работу с ним. ppStmt может не быть NULL.

При успехе sqlite3_prepare() вернет SQLITE_OK, иначе код ошибки.

sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() рекомендуются для всех новых программ. Более старые интерфейсы (sqlite3_prepare() и sqlite3_prepare16()) сохраняются для обратной совместимости, но их использование не рекомендуется. В интерфейсах "vX" подготовленный запрос, который возвращен (объект sqlite3_stmt) содержит копию оригинального кода на SQL. Это заставляет sqlite3_step() вести себя по-другому тремя путями:

1. Если схема базы данных изменится, вместо того, чтобы возвратить SQLITE_SCHEMA как это всегда раньше делало, sqlite3_step() автоматически повторно соберет SQL-оператор и делает попытку управлять им снова. Будет SQLITE_MAX_SCHEMA_RETRY попыток прежде, чем sqlite3_step() сдается и возвращает ошибку.
2. Когда ошибка произойдет, sqlite3_step() возвратит одни из подробных кодов ошибки или расширенных кодов ошибки. Устаревшее поведение состояло в том, что sqlite3_step() возвратит только универсальный код результата SQLITE_ERROR и приложение должно было сделать второй вызов sqlite3_reset(), чтобы найти первопричину проблемы. С интерфейсами "v2" основная причина ошибки немедленно возвращена.
3. Если определенное значение, связанное с параметром хоста в WHERE, могло бы влиять на выбор плана запроса, запрос будет автоматически повторно собран, как будто было изменение схемы на первом вызове sqlite3_step() после любого изменения привязок параметров. Определенное значение WHERE-параметра могло бы влиять на выбор плана запросов, если параметр левая сторона LIKE или GLOB, или если параметр сравнивается с индексированным столбцом и включен выбор времени компиляции SQLITE_ENABLE_STAT4.

sqlite3_prepare_v3() отличается от sqlite3_prepare_v2() только наличием дополнительного параметра prepFlags, который является маленьким множеством, состоящим из ноля или большего количества флагов SQLITE_PREPARE_*. sqlite3_prepare_v2() работает аналогично sqlite3_prepare_v3() с нулевым параметром prepFlags.

---

Отзывы разрешения времени компиляции

int sqlite3_set_authorizer(sqlite3*, int (*xAuth)(void*,int,const char*,
                           const char*,const char*,
                           const char*), void *pUserData);

Это регистрирует отзыв авторизатора в конкретном соединении с базой данных, поставляемом в первом аргументе. Авторизатор вызван, поскольку SQL-операторы собираются sqlite3_prepare() или его вариантами sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3(). В различных пунктах во время процесса компиляции, когда логика создается, чтобы выполнить различные действия, авторизатор вызван, чтобы видеть, позволены ли те действия. Авторизатор должен возвратить SQLITE_OK, чтобы позволить действие, SQLITE_IGNORE, чтобы отвергнуть определенное действие, но позволить SQL-оператору продолжать собираться, или SQLITE_DENY, чтобы заставить весь SQL-оператор быть отклоненным с ошибкой. Если авторизатор возвратит какое-либо значение кроме SQLITE_IGNORE, SQLITE_OK или SQLITE_DENY, sqlite3_prepare_v2() или эквивалентный запрос, который вызвал авторизатор, потерпит неудачу с сообщением об ошибке.

Когда отзыв возвращает SQLITE_OK, это означает, что операция, которую требуют, в порядке. Когда отзыв возвращает SQLITE_DENY, sqlite3_prepare_v2(), который вызвал авторизатор, потерпит неудачу с сообщением об ошибке, объясняя, что доступ закрыт.

Первый параметр авторизатора это копия третьего параметра sqlite3_set_authorizer(). Второй параметр это integer action code, который определяет конкретное действие, которое будет разрешено. С третьего по шестой параметры отзыва являются NULL или законченные нолем последовательности, которые содержат дополнительные детали о действии, которое будет разрешено. Запросы должны всегда быть готовы столкнуться с NULL в любом из этих параметров отзыва авторизатора.

Если код действия SQLITE_READ и отзыв возвращает SQLITE_IGNORE, подготовленный запрос построен, чтобы поставить NULL вместо столбца таблицы, который был бы прочитан, если бы вернулся SQLITE_OK. Возвращение SQLITE_IGNORE может использоваться, чтобы лишить пользовательского доступа, которому не доверяют, к отдельным столбцам таблицы. Когда на таблицу ссылается SELECT, но никакие значения столбцов не извлечены из той таблицы (например, в запросе вроде "SELECT count(*) FROM tab"), то SQLITE_READ отзыв вызван однажды для той таблицы с именем столбца, которое является пустой строкой. Если код действия SQLITE_DELETE и отзыв возвращает SQLITE_IGNORE, DELETE обрабатывается, но усеченная оптимизация отключена, и все строки удалены индивидуально.

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

Запросы, которые должны обработать SQL из источников, которым не доверяют, могли бы также рассмотреть понижающиеся пределы ресурса, используя sqlite3_limit() и ограничив размер базы данных, используя max_page_count PRAGMA в дополнение к использованию авторизатора.

Только единственный авторизатор может существовать на соединении с базой данных за один раз. Каждый запрос sqlite3_set_authorizer отвергает предыдущий запрос. Отключите авторизатор, установив отзыв NULL. Авторизатор отключен по умолчанию.

Отзыв авторизатора не должен делать ничего, что изменит соединение с базой данных, которое вызвало авторизатор, в том числе вызывать sqlite3_prepare_v2() и sqlite3_step().

Когда sqlite3_prepare_v2() используется, чтобы подготовить запрос, он мог бы быть повторно подготовлен во время sqlite3_step() из-за изменения схемы. Следовательно, приложение должно гарантировать, что правильный отзыв авторизатора остается на месте во время sqlite3_step().

Обратите внимание на то, что отзыв авторизатора вызван только во время sqlite3_prepare() или его вариантов. Разрешение не выполняется во время оценки запроса в sqlite3_step(), если, как указано в предыдущем параграфе, sqlite3_step() не вызывает sqlite3_prepare_v2(), чтобы повторно подготовить запрос после изменения схемы.

---

Тест на режим Auto-Commit

int sqlite3_get_autocommit(sqlite3*);

sqlite3_get_autocommit() возвращает отличное от нуля значение или ноль, если данное соединение с базой данных находится или не находится в режиме autocommit, соответственно. Autocommit включен по умолчанию. Autocommit отключен запросом BEGIN. Autocommit включен назад запросами COMMIT и ROLLBACK.

Если определенные виды ошибок происходят на запросе в транзакции мультизапроса (включая SQLITE_FULL, SQLITE_IOERR, SQLITE_NOMEM, SQLITE_BUSY и SQLITE_INTERRUPT), транзакция могла бы быть понижена до прежнего уровня автоматически. Единственный режим узнать, понизил ли SQLite автоматически транзакцию до прежнего уровня после ошибки, состоит в том, чтобы использовать эту функцию.

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

---

Зарегистрируйте отзыв, чтобы обработать ошибки SQLITE_BUSY

int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);

sqlite3_busy_handler(D,X,P) устанавливает функцию обратного вызова X, который мог бы быть вызван с аргументом P каждый раз, когда предпринята попытка получить доступ к таблице базы данных, связанной с соединением с базой данных D, когда другой поток или процесс заблокировал таблицу. sqlite3_busy_handler() используется, чтобы осуществить sqlite3_busy_timeout() и PRAGMA busy_timeout.

Если занятый отзыв NULL, то SQLITE_BUSY возвращен непосредственно после столкновения с блокировкой. Если занятый отзыв не NULL, то отзыв мог бы быть вызван с двумя аргументами.

Первый аргумент занятому обработчику это копия указателя void*, который является третьим аргументом sqlite3_busy_handler(). Второй аргумент занятому отзыву обработчика это число раз, которое обработчик был вызван ранее для того же самого события. Если занятый отзыв возвращает 0, то никакие дополнительные попытки не предприняты, чтобы получить доступ к базе данных, и SQLITE_BUSY возвращен приложению. Если отзыв вернет значение, отличное от нуля, то другая попытка предпринята, чтобы получить доступ к базе данных и повторениям цикла.

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

По умолчанию отзыв является NULL.

Может только быть единственный обработчик, определенный для каждого соединения с базой данных. Урегулирование нового занятого обработчика очищает любой заданный ранее обработчик. Обратите внимание на то, что, вызов sqlite3_busy_timeout() или PRAGMA busy_timeout=N изменит занятого обработчика и таким образом очистит заданный ранее.

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

Занятой обработчик не должен закрывать соединение с базой данных или подготовленный запрос, который вызвал занятого обработчика.

---

Значения результата от запроса

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);

Обзор:

sqlite3_column_blob	→	BLOB
sqlite3_column_double	→	REAL
sqlite3_column_int	→	32-bit INTEGER
sqlite3_column_int64	→	64-bit INTEGER
sqlite3_column_text	→	UTF-8 TEXT
sqlite3_column_text16	→	UTF-16 TEXT
sqlite3_column_value	→	Результат как объект unprotected sqlite3_value.
sqlite3_column_bytes	→	Размер результата BLOB или UTF-8 TEXT в байтах
sqlite3_column_bytes16	→	Размер UTF-16 TEXT в байтах
sqlite3_column_type	→	Тип данных по умолчанию для результата

Детали:

Это возвращает информацию об отдельном столбце текущей строки результата запроса. В каждом случае первый аргумент это указатель на подготовленный запрос, который оценивается (sqlite3_stmt*, который был возвращен из sqlite3_prepare_v2() или один из его вариантов), второй аргумент это индекс колонки, для которой должна быть возвращена информация. У крайнего левого столбца набора результатов индекс 0. Количество колонок в результате может быть определено, используя sqlite3_column_count().

Если SQL-оператор в настоящее время не указывает на действительную строку или если индекс столбца вне диапазона, результат не определен. Это можно вызвать только, когда новый запрос к sqlite3_step() вернул SQLITE_ROW и sqlite3_reset() или sqlite3_finalize() не вызвали впоследствии. Если sqlite3_reset(), sqlite3_finalize() или sqlite3_step() вернула что-то кроме SQLITE_ROW, результаты не определены. Если sqlite3_step(), sqlite3_reset() или sqlite3_finalize() вызывают из другого потока в то время как эта процедура выполняется, то результаты не определены.

Первые шесть интерфейсов (_blob, _double, _int, _int64, _text и _text16) возвращает значение столбца результата в определенном формате данных. Если столбец результата не находится первоначально в запрашиваемом формате (например, если запрос возвращает целое число, но sqlite3_column_text() используется, чтобы извлечь значение), тогда выполняется автоматическое преобразование типов.

sqlite3_column_type() вернет код типа данных для типа исходных данных столбца результата. Возвращенное значение одно из SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB или SQLITE_NULL. Возвращаемое значение sqlite3_column_type() может использоваться, чтобы решить, какой из первых шести интерфейсов должен использоваться, чтобы извлечь значение столбца. Значение, возвращенное sqlite3_column_type(), значащее только если никакие автоматические преобразования типов не произошли для рассматриваемого значения. После преобразования типов результат запроса sqlite3_column_type() не определен, хотя безопасен. Будущие версии SQLite могут изменить поведение sqlite3_column_type() после преобразования типов.

Если результат BLOB или TEXT, sqlite3_column_bytes() или sqlite3_column_bytes16() может использоваться, чтобы определить размер того BLOB или последовательности.

Если результат BLOB или строка UTF-8, sqlite3_column_bytes() возвращает число байтов в том BLOB или последовательности. Если результат последовательность UTF-16, то sqlite3_column_bytes() преобразовывает последовательность в UTF-8 и затем возвращает число байтов. Если результат числовое значение, тогда sqlite3_column_bytes() применяет sqlite3_snprintf(), чтобы преобразовать значение в последовательность UTF-8 и возвращает число байтов в той последовательности. Если результат NULL, то sqlite3_column_bytes() вернет 0.

Если результат BLOB или строка в UTF-16, sqlite3_column_bytes16() возвращает число байтов в том BLOB или последовательности. Если результат последовательность UTF-8, то sqlite3_column_bytes16() преобразовывает последовательность в UTF-16 и затем возвращает число байтов. Если результат числовое значение, тогда sqlite3_column_bytes16() использует sqlite3_snprintf(), чтобы преобразовать значение в последовательность UTF-16 и возвращает число байтов в той последовательности. Если результат NULL, то sqlite3_column_bytes16() вернет 0.

Значения, возвращенные sqlite3_column_bytes() и sqlite3_column_bytes16(), не включают нулевых терминаторов в конце последовательности. Для ясности: значения, возвращенные sqlite3_column_bytes() и sqlite3_column_bytes16(), являются числом байтов в последовательности, но не количеством знаков.

Последовательности, возвращенные sqlite3_column_text() и sqlite3_column_text16(), даже пустые строки, всегда заканчиваются нолем. Возвращаемое значение sqlite3_column_blob() для нулевой длины BLOB является NULL.

У последовательностей, возвращенных sqlite3_column_text16(), всегда есть завершитель, который является родным на платформе, независимо от текстового набора кодирования для базы данных.

Предупреждение: объект, возвращенный sqlite3_column_value(), это объект unprotected sqlite3_value. В многопоточной окружающей среде незащищенный объект sqlite3_value может использоваться безопасно только с sqlite3_bind_value() и sqlite3_result_value(). Если объект unprotected sqlite3_value, возвращенный sqlite3_column_value(), используется каким-либо другим способом, включая вызовы функций вроде sqlite3_value_int(), sqlite3_value_text() или sqlite3_value_bytes(), поведение не ориентировано на многопоточное исполнение. Следовательно, sqlite3_column_value() обычно полезен только в рамках внедрения определяемых SQL-функций или виртуальных таблиц, но не в рамках кода приложения верхнего уровня.

Это может попытаться преобразовать тип данных результата. Например, если внутреннее представление FLOAT и текстовый результат требуют, sqlite3_snprintf() используется внутренне, чтобы выполнить преобразование автоматически. Следующая таблица детализирует преобразования, которые применяются:

Внутренний тип	Тип результата	Преобразование
NULL	INTEGER	Результат 0
NULL	FLOAT	Результат 0.0
NULL	TEXT	Результат NULL
NULL	BLOB	Результат NULL
INTEGER	FLOAT	Преобразование из integer в float
INTEGER	TEXT	Представление ASCII integer
INTEGER	BLOB	Ааналогично INTEGER->TEXT
FLOAT	INTEGER	CAST в INTEGER
FLOAT	TEXT	Представление ASCII float
FLOAT	BLOB	CAST в BLOB
TEXT	INTEGER	CAST в INTEGER
TEXT	FLOAT	CAST в REAL
TEXT	BLOB	Без изменений
BLOB	INTEGER	CAST в INTEGER
BLOB	FLOAT	CAST в REAL
BLOB	TEXT	CAST в TEXT, гарантируйте нулевой терминатор

Обратите внимание на то, что, когда преобразования типов происходят, указатели, возвращенные предшествующими sqlite3_column_blob(), sqlite3_column_text() и/или sqlite3_column_text16(), могут быть лишены законной силы. Преобразования типов и аннулирование указателя могли бы произойти в следующих случаях:

• Начальное содержание BLOB и вызвана sqlite3_column_text() или sqlite3_column_text16(). Нулевой терминатор, возможно, должен был быть добавлен к последовательности.
• Начальное содержание текст в UTF-8 м вызвана sqlite3_column_bytes16() или sqlite3_column_text16(). Содержание должно быть преобразовано в UTF-16.
• Начальное содержание текст в UTF-16 и вызвана sqlite3_column_bytes() или sqlite3_column_text(). Содержание должно быть преобразовано в UTF-8.

Преобразования между UTF-16be и UTF-16le всегда делаются на месте и не лишают законной силы обратный указатель, хотя, конечно, содержание буфера будет изменено. Другие виды преобразования сделаны на месте, когда это возможно, но иногда они невозможны, и в тех случаях лишены законной силы обратные указатели.

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

• sqlite3_column_text() сопровождаемый sqlite3_column_bytes()
• sqlite3_column_blob() сопровождаемый sqlite3_column_bytes()
• sqlite3_column_text16() сопровождаемый sqlite3_column_bytes16()

Другими словами, необходимо вызвать sqlite3_column_text(), sqlite3_column_blob() или sqlite3_column_text16() сначала, чтобы привести результат в нужный формат, затем вызвать sqlite3_column_bytes() или sqlite3_column_bytes16(), чтобы найти размер результата. Не смешивайте требования к sqlite3_column_text() или sqlite3_column_blob() с вызовами sqlite3_column_bytes16() и sqlite3_column_text16() с sqlite3_column_bytes().

Возвращенные указатели действительны, пока преобразование типов не происходит, как описано выше, или до вызова sqlite3_step(), sqlite3_reset() или sqlite3_finalize(). Пространство памяти, используемое, чтобы хранить последовательности и BLOB, освобождено автоматически. Не передавайте указатели, возвращенные sqlite3_column_blob(), sqlite3_column_text() и т.д., в sqlite3_free().

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

• sqlite3_column_blob()
• sqlite3_column_text()
• sqlite3_column_text16()
• sqlite3_column_bytes()
• sqlite3_column_bytes16()

Если ошибка памяти происходит, то возвращаемое значение такое, как если бы колонка содержала SQL NULL. Действительный SQL NULL можно отличить от ошибок памяти, вызвав sqlite3_errcode() немедленно после того, как подозрительное возвращаемое значение получено и прежде чем любой другой интерфейс SQLite вызовут на том же самом соединении с базой данных.

---

Контроль низкого уровня файлов базы данных

int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

sqlite3_file_control() делает прямой вызов метода xFileControl для объекта sqlite3_io_methods, связанного с конкретной базой данных, определенной вторым аргументом. Название базы данных "main" для главной базы данных или "temp" для базы данных TEMP или имени, которое появляется после ключевого слова AS для баз данных, которые добавляются, используя команду SQL ATTACH. Указатель NULL может использоваться вместо "main", чтобы относиться к главному файлу базы данных. Третьи и четвертые параметры передаются непосредственно к вторым и третьим параметрам метода xFileControl. Возвращаемое значение метода xFileControl становится возвращаемым значением этой функции.

Несколько кодов операции для sqlite3_file_control() обработаны непосредственно ядром SQLite и никогда не вызывают sqlite3_io_methods.xFileControl. Значение SQLITE_FCNTL_FILE_POINTER для параметра op заставляет указатель на основной объект sqlite3_file быть написанным в буфер, на который указывает 4-й параметр. SQLITE_FCNTL_JOURNAL_POINTER работает так же за исключением того, что он возвращает объект sqlite3_file, связанный с файлом журнала вместо главной базы данных. Код операции SQLITE_FCNTL_VFS_POINTER вернет указатель на основной объект sqlite3_vfs для файла. SQLITE_FCNTL_DATA_VERSION возвращает счетчик версии данных из страниц.

Если второй параметр (zDbName) не соответствует названию никакого открытого файла базы данных, то SQLITE_ERROR возвращен. Этот код ошибки не запоминается и не восстанавливается sqlite3_errcode() или sqlite3_errmsg(). Основной метод xFileControl мог бы также возвратить SQLITE_ERROR. Нет никакого режима различать неправильный zDbName и возвращение SQLITE_ERROR из основного метода xFileControl.

---

Создайте или пересмотрите функции SQL

int sqlite3_create_function(sqlite3 *db, const char *zFunctionName,
                            int nArg, int eTextRep, void *pApp,
                            void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
                            void (*xStep)(sqlite3_context*,int,sqlite3_value**),
                            void (*xFinal)(sqlite3_context*));

int sqlite3_create_function16(sqlite3 *db, const void *zFunctionName,
                              int nArg, int eTextRep, void *pApp,
                              void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
                              void (*xStep)(sqlite3_context*,int,sqlite3_value**),
                              void (*xFinal)(sqlite3_context*));

int sqlite3_create_function_v2(sqlite3 *db, const char *zFunctionName,
                               int nArg, int eTextRep, void *pApp,
                               void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
                               void (*xStep)(sqlite3_context*,int,sqlite3_value**),
                               void (*xFinal)(sqlite3_context*),
                               void(*xDestroy)(void*));

int sqlite3_create_window_function(sqlite3 *db, const char *zFunctionName,
                                   int nArg, int eTextRep, void *pApp,
                                   void (*xStep)(sqlite3_context*,int,
                                        sqlite3_value**),
                                   void (*xFinal)(sqlite3_context*),
                                   void (*xValue)(sqlite3_context*),
                                   void (*xInverse)(sqlite3_context*,int,
                                        sqlite3_value**),
                                   void(*xDestroy)(void*));

Эти функции (коллективно известны как "режимы создания функции") используются, чтобы добавить функции SQL или совокупности или пересмотреть поведение существующих функций SQL или совокупностей. Единственными различиями между тремя "sqlite3_create_function*" является текстовое кодирование, ожидаемое для второго параметра (название создаваемой функции) и присутствие или отсутствие отзыва деструктора для указателя данных приложения. Функция sqlite3_create_window_function() подобна, но позволяет пользователю поставлять дополнительные функции обратного вызова, необходимые совокупным функциям окна.

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

Второй параметр это название функции SQL, которая будет создана или пересмотрена. Длина имени ограничивается 255 байтами в представлении UTF-8, не считая нулевого терминатора. Обратите внимание на то, что предел длины имени задан в байтах UTF-8, а не знаках или байтах UTF-16. Любая попытка создать функцию с более длинным именем приведет к возврату SQLITE_MISUSE.

Третий параметр (nArg) является количеством аргументов, которые функция SQL или совокупность берут. Если этот параметр -1, функция SQL или совокупность могут взять любое количество параметров между 0 и пределом sqlite3_limit( SQLITE_LIMIT_FUNCTION_ARG). Если третий параметр меньше -1 или больше 127, поведение не определено.

Четвертый параметр, eTextRep, определяет то, что текст, кодирующий эту функцию SQL, предпочитает для ее параметров. Приложение должно установить этот параметр в SQLITE_UTF16LE, если реализация функции вызывает sqlite3_value_text16le() на входе, SQLITE_UTF16BE, если внедрение вызывает sqlite3_value_text16be(), SQLITE_UTF16, если sqlite3_value_text16() используется, или SQLITE_UTF8 иначе. Та же самая функция SQL может быть зарегистрирована многократно, используя различное предпочтительное текстовое кодирование с различными внедрениями для каждого кодирования. Когда многократные внедрения той же самой функции будут доступны, SQLite выберет тот, который включает наименьшее количество преобразований объема данных.

Четвертый параметр может произвольно быть OR с SQLITE_DETERMINISTIC, чтобы сигнализировать, что функция будет всегда возвращать тот же самый результат, имея те же самые данные в единственном SQL-операторе. Большинство функций SQL детерминировано. Встроенная функция SQL random() это пример функции, которая не детерминирована. Планировщик запроса SQLite в состоянии выполнить дополнительную оптимизацию на детерминированных функциях, таким образом, использование флага SQLITE_DETERMINISTIC рекомендуется, если это возможно.

Четвертый параметр может также произвольно включать флаг SQLITE_DIRECTONLY, который, если есть, препятствует тому, чтобы функция была вызвана из VIEW, TRIGGER, ограничения CHECK, выражения создания колонки, выражения индекса или оператора Where частичных индексов.

Для лучшей безопасности флаг SQLITE_DIRECTONLY рекомендуется для всех определенные приложением функции SQL, которые не должны использоваться в VIEW, TRIGGER, ограничениях CHECK или других элементах схемы базы данных. Это особенно рекомендуется для функций SQL, которые имеют побочные эффекты или показывают статус внутреннего приложения. Без этого флага нападавший мог бы быть в состоянии изменить схему файла базы данных, чтобы включать вызовы функции с параметрами, выбранными нападавшим, когда файл базы данных будет открыт и читается.

Пятый параметр это произвольный указатель. Внедрение функции может получить доступ к этому указателю, используя sqlite3_user_data().

Шестые, седьмые и восьмые параметры, переданные трем функциям, это xFunc, xStep и xFinal, являются указателями на функции языка C, которые осуществляют функцию SQL или совокупность. Скалярная функция SQL требует внедрения только отзыва xFunc, NULL должен быть передан как параметры xStep и xFinal. Совокупная функция SQL требует внедрения xStep и xFinal, NULL должен быть передан для xFunc. Чтобы удалить существующую функцию SQL или совокупность, передайте NULL для всех трех отзывов функции.

Шестые, седьмые, восьмые и девятые параметры (xStep, xFinal, xValue и xInverse) для sqlite3_create_window_function это указатели на отзывы языка C, которые осуществляют новую функцию. xStep и xFinal должны оба быть не NULL. xValue и xInverse могут или оба быть NULL (в этом случае регулярная агрегатная функция создается) или должны оба быть не NULL (в этом случае новая функция может использоваться в качестве совокупной или в качестве совокупной функции окна). Больше деталей относительно внедрения совокупных функций окна доступно здесь.

Если заключительным параметром sqlite3_create_function_v2() или sqlite3_create_window_function() будет не NULL, то это деструктор для указателя данных приложения. Деструктор вызван, когда функция удалена, будучи перегруженной или когда соединение с базой данных закрывается. Деструктор также вызван, если запрос sqlite3_create_function_v2() неудачен. Когда отзыв деструктора вызван, ему передается отдельный аргумент, который является копией указателя данных приложения, который был пятым параметром sqlite3_create_function_v2().

Разрешено зарегистрировать многократные внедрения тех же самых функций с тем же самым именем, но с отличающимися числами аргументов или с отличающимся предпочтительным текстовым кодированием. SQLite будет использовать внедрение, которое наиболее соответствует пути, которым используется функция SQL. Реализация функции с неотрицательным параметром nArg это лучшее соответствие, чем реализация функции с отрицательным nArg. Функция, где предпочтительный текст, кодирующий, соответствует кодированию базы данных, является лучшим соответствием, чем функция, где кодирование отличается. Функция, где различие в кодировании между UTF16le и UTF16be, является более близким соответствием, чем функция, где различие в кодировании между UTF8 и UTF16.

Встроенные функции могут быть перегружены новыми определенными приложением функциями.

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