Спецификация интерфейса SQLite на языке C

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

• SQLite за 3 минуты или меньше и/или
• введению в интерфейс SQLite C/C++.

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

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

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

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

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

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

Ключевые моменты:

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

Список объектов:

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

Также доступен: список кодов ошибок

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

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

Флаги для 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 до этого верхнего предела в качестве аргумента «смещение». Ядро SQLite никогда не будет пытаться получить или освободить блокировку за пределами этого диапазона.

Обработка внешних расширений

typedef struct sqlite3_api_routines sqlite3_api_routines;

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

Объект резервного копирования в режиме онлайн

typedef struct sqlite3_backup sqlite3_backup;

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

См. также: Использование API резервного копирования SQLite в режиме онлайн

Объект контекста 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 Windows, будут считаться относительными к этой директории. Если эта переменная является указателем NULL, то SQLite предполагает, что все файлы базы данных, указанные с относительным путем, относительны к текущей директории процесса. Только VFS Windows использует эту глобальную переменную; она игнорируется VFS Unix.

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

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

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

Дескриптор открытого файла интерфейса ОС

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

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

Имя файла

typedef const char *sqlite3_filename;

Тип sqlite3_filename используется SQLite для передачи имён файлов в метод xOpen VFS. Он может быть приведён к типу (const char*) и обрабатываться как обычный нуль-терминированный буфер 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 модуля виртуальной таблицы и получения ответа от него. Поля в разделе **Входные данные** являются входными данными для xBestIndex и являются только для чтения. xBestIndex вставляет свои результаты в поля **Выходные данные**.

Массив aConstraint[] записывает ограничения условия WHERE в форме:

столбец ОП выражение

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

Оптимизатор автоматически инвертирует термины вида «выражение ОП столбец» и выполняет другие упрощения условия 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_HEX, который, если он установлен, вызывает вывод EXPLAIN QUERY PLAN, чтобы показать idxNum в шестнадцатеричном, а не в десятичном формате. Другой флаг — SQLITE_INDEX_SCAN_UNIQUE, который, если он установлен, указывает, что план запроса вернёт не более одной строки.

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

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

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

Объект виртуальных методов файлового интерфейса ОС

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 в указатель, отличный от NULL, то метод sqlite3_io_methods.xClose может быть вызван даже если метод sqlite3_vfs.xOpen сообщил об ошибке. Единственный способ предотвратить вызов xClose после неудачного sqlite3_vfs.xOpen заключается в том, чтобы метод sqlite3_vfs.xOpen установил элемент sqlite3_file.pMethods в значение NULL.

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

Целочисленные значения для xLock() и 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 для собственного использования. Список кодов операций кодов операций меньше 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. Некоторые механизмы округляют до большего кратного или до степени двойки. Каждый запрос выделения памяти, поступающий через sqlite3_malloc() или sqlite3_realloc(), сначала вызывает xRoundup. Если xRoundup возвращает 0, это приводит к ошибке соответствующего выделения памяти.

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

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

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

Дескриптор мьютекса

typedef struct sqlite3_mutex sqlite3_mutex;

Модуль мьютексов в SQLite определяет sqlite3_mutex как абстрактный тип для объекта мьютекса. Ядро SQLite никогда не анализирует внутреннее представление объекта sqlite3_mutex. Оно работает только с указателями на объект sqlite3_mutex.

Мьютексы создаются с помощью sqlite3_mutex_alloc().

Объект методов мьютекса

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 *);
};

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

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

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

Метод xMutexEnd, определённый в этой структуре, вызывается как часть завершения системы функцией sqlite3_shutdown(). Реализация этого метода должна освободить все задействованные ресурсы, полученные реализацией методов мьютекса, особенно те, которые получены методом 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()

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

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

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

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

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

typedef struct sqlite3_pcache sqlite3_pcache;

Тип sqlite3_pcache является непрозрачным. Он реализован подключаемым модулем. Ядро SQLite не знает его размера или внутренней структуры и никогда не работает с объектом sqlite3_pcache, кроме как удерживая и передавая указатели на объект.

См. sqlite3_pcache_methods2 для получения дополнительной информации.

Объект страницы пользовательского кэша

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 представляет собой отдельную страницу в кэше страниц. Кэш страниц будет выделять экземпляры этого объекта. Различные методы кэша страниц используют указатели на экземпляры этого объекта в качестве параметров или возвращаемого значения.

См. sqlite3_pcache_methods2 для получения дополнительной информации.

Имя папки, содержащей временные файлы

SQLITE_EXTERN char *sqlite3_temp_directory;

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

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

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

Pragma temp_store_directory может изменить эту переменную и сделать ее указывающей на память, полученную из sqlite3_malloc. Кроме того, pragma temp_store_directory всегда предполагает, что любая строка, на которую указывает эта переменная, хранится в памяти, полученной из sqlite3_malloc, и pragma может попытаться освободить эту память с помощью sqlite3_free. Следовательно, если эта переменная изменяется напрямую, она должна быть установлена в NULL или должна указывать на память, полученную из sqlite3_malloc, или же следует избегать использования pragmy temp_store_directory. За исключением запроса со стороны pragmy temp_store_directory, 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);

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

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» в имени объекта означает «виртуальная файловая система». Дополнительную информацию см. в документации по VFS.

Интерфейс VFS иногда расширяется путем добавления новых методов в конец. Каждый раз, когда такое расширение происходит, поле iVersion увеличивается. Значение iVersion начиналось с 1 в SQLite версии 3.5.0 от 2007-09-04, затем увеличилось до 2 с SQLite версии 3.7.0 от 2010-07-21, а затем увеличилось до 3 с SQLite версии 3.7.6 от 2011-04-12. К объекту sqlite3_vfs могут быть добавлены дополнительные поля, а значение iVersion может снова увеличиться в будущих версиях SQLite. Обратите внимание, что из-за упущения структура объекта sqlite3_vfs изменилась при переходе от SQLite версии 3.5.9 к версии 3.6.0 от 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 будет обращаться к этому полю или изменять его только при удержании определенного статического мьютекса. Приложение никогда не должно изменять что-либо внутри объекта sqlite3_vfs после его регистрации.

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

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

Аргумент flags метода xOpen() включает все биты, установленные в аргументе flags для sqlite3_open_v2(). Или, если используется sqlite3_open() или sqlite3_open16(), то flags включает по крайней мере SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. Если xOpen() открывает файл только для чтения, то он устанавливает *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. Или же реализация может распознать, что файл базы данных будет выполнять чтение и запись сектора с выравниванием по страницам в произвольном порядке, и соответствующим образом настроить свою систему ввода-вывода.

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

• SQLITE_OPEN_DELETEONCLOSE
• SQLITE_OPEN_EXCLUSIVE

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

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

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

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

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

Интерфейсы xRandomness(), xSleep(), xCurrentTime() и xCurrentTimeInt64() не являются строго частью файловой системы, но включены в структуру VFS для полноты. Функция xRandomness() пытается вернуть nBytes байтов качественного случайного числа в zOut. Возвращаемое значение — фактическое количество полученных байтов случайности. Метод xSleep() заставляет вызывающий поток ждать не менее заданного количества микросекунд. Метод xCurrentTime() возвращает число Джулианского дня для текущей даты и времени в виде значения с плавающей точкой. Метод xCurrentTimeInt64() возвращает, как целое число, число Джулианского дня, умноженное на 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, которая уже находится в списке автоматических расширений, является безобидным действием без эффектов. Ни одна точка входа не будет вызвана более одного раза для каждого открытого соединения с базой данных.

См. также: sqlite3_reset_auto_extension() и sqlite3_cancel_auto_extension()

Обратный вызов количества уплотнения автовакуума

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), имя схемы подключенной базы данных, которая подвергается автовакууму, размер файла базы данных в страницах, количество свободных страниц и количество байтов на страницу соответственно. Обратный вызов должен вернуть количество свободных страниц, которые должны быть удалены автовакуумом. Если обратный вызов возвращает ноль, то автовакуум не происходит. Если возвращаемое значение больше или равно количеству свободных страниц, то происходит полный автовакуум.

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

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

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

Для каждого соединения с базой данных существует только один обратный вызов 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, в списке могут быть пробелы.

См. также: sqlite3_bind(), sqlite3_bind_parameter_name() и sqlite3_bind_parameter_index().

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

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

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

См. также: sqlite3_bind(), sqlite3_bind_parameter_count() и sqlite3_bind_parameter_name().

Имя параметра

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» соответственно. Другими словами, начальный символ «:», «$», «@» или «?» включается в состав имени. Параметры вида «?» без последующего целого числа не имеют имени и называются «безымянными» или «анонимными параметрами».

Первый параметр имеет индекс 1, а не 0.

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

См. также: sqlite3_bind(), sqlite3_bind_parameter_count() и sqlite3_bind_parameter_index().

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

int sqlite3_blob_bytes(sqlite3_blob *);

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

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

Закрытие дескриптора BLOB

int sqlite3_blob_close(sqlite3_blob *);

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

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

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

Открыть BLOB для инкрементного ввода-вывода

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".

Если параметр flags не равен нулю, то BLOB открывается для чтения и записи. Если параметр flags равен нулю, 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.

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

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

Интерфейсы sqlite3_bind_zeroblob() и sqlite3_result_zeroblob(), а также встроенная функция SQL zeroblob могут быть использованы для создания нулевого BLOB для чтения или записи с помощью интерфейса инкрементного 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, остаются неизменными. Перемещение существующего дескриптора BLOB в новую строку быстрее, чем закрытие существующего дескриптора и открытие нового.

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

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

Запись данных в 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, переданный в качестве первого аргумента, не был открыт для записи (параметр flags для 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, не отменяются истечением срока действия дескриптора, хотя, конечно, эти изменения могут быть перезаписаны оператором, который истекает срок действия дескриптора 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, если инициализационная функция X была успешно отменена, и 0, если X отсутствует в списке инициализационных функций.

Сброс всех привязок в подготовленном запросе

int sqlite3_clear_bindings(sqlite3_stmt*);

Вопреки распространённому мнению, sqlite3_reset() не сбрасывает привязки в подготовленном запросе. Используйте эту функцию для сброса всех параметров клиента в 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, чтобы настроить её под конкретные потребности приложения. Для большинства приложений рекомендуется использовать стандартную конфигурацию, поэтому этот интерфейс обычно не требуется. Он предоставляется для поддержки редких приложений с необычными потребностями.

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

Первый аргумент функции sqlite3_config() — целое число опция конфигурации, определяющая, какой аспект 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() возвращает копию указателя на подключение к базе данных (первый параметр) функций 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, где она всегда возвращает ноль, так как каждый шаг этого многошагового пragma возвращает 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) должен быть указателем на имя файла, переданным методу xOpen sqlite3_vfs, где параметр flags в 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.

Если во время очистки грязных страниц на диск произошла любая другая ошибка (например, ошибка ввода-вывода или состояние недостатка памяти), обработка прекращается, и немедленно возвращается код ошибки 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,...) — глагол конфигурации — целое число, которое указывает, какой аспект подключения к базе данных настраивается. Последующие аргументы зависят от глагола конфигурации.

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

Возвращение имени файла для подключения к базе данных

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

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

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

Имя файла, возвращаемое этой функцией, является результатом работы метода 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() (или его вариантах), который использовался для создания запроса в самом начале.

Получение мьютекса для подключения к базе данных

sqlite3_mutex *sqlite3_db_mutex(sqlite3*);

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

Возвращение имени схемы для подключения к базе данных

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

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

Пространство для хранения строки, возвращаемой функцией sqlite3_db_name(), управляется самой SQLite. Строка может быть освобождена любой операцией, изменяющей схему, включая ПРИСОЕДИНЕНИЕ или ОТДЁЛЁННОЕ или вызовы sqlite3_serialize() или sqlite3_deserialize(), даже операции, выполняемые в другом потоке. Приложениям, которым необходимо запомнить строку надолго, следует сделать свою копию. Приложениям, одновременно обращаящимся к одному и тому же соединению с базой данных из нескольких потоков, следует защитить вызовы этого API с помощью мьютекса и создать собственную частную копию результата перед освобождением мьютекса.

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

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);

Этот интерфейс используется для получения информации о текущем состоянии одиночного соединения с базой данных. Первый аргумент — объект соединения с базой данных, который нужно проверить. Второй аргумент — целочисленная константа из набора параметров 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-инъекции, дающие злоумышленникам доступ к возможностям загрузки расширений.

Включение или отключение кэша общих пейджеров

int sqlite3_enable_shared_cache(int);

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

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

Совместное использование кэша включено или выключено для всего процесса. Это изменение, начиная с версии SQLite 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 версии 5.0 и всегда вернёт SQLITE_MISUSE. На этих системах режим совместного использования кэша должен быть включён для каждого соединения с базой данных через sqlite3_open_v2() с флагом SQLITE_OPEN_SHAREDCACHE.

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

См. также: Режим совместного использования кэша SQLite

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

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() выполняет нулевые или более UTF-8 кодированные SQL-заявления, разделённые точкой с запятой, переданные в его второй аргумент, в контексте соединения с базой данных, переданного в качестве первого аргумента. Если функция обратного вызова в третьем аргументе sqlite3_exec() не равна NULL, она вызывается для каждой строки результата, получаемой из оцениваемых SQL-заявлений. Четвёртый аргумент sqlite3_exec() передаётся первому аргументу каждого вызова обратного вызова. Если указатель на функцию обратного вызова в sqlite3_exec() равен NULL, обратный вызов никогда не вызывается, и строки результатов игнорируются.

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

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

Вторым аргументом обратного вызова функции sqlite3_exec() является количество столбцов в результате. Третий аргумент обратного вызова sqlite3_exec() — массив указателей на строки, полученные как будто из sqlite3_column_text(), по одному на каждый столбец. Если элемент строки результата равен NULL, то соответствующий указатель на строку для обратного вызова sqlite3_exec() также равен NULL. Четвертый аргумент обратного вызова sqlite3_exec() — массив указателей на строки, где каждая запись представляет имя соответствующего столбца результата, полученное из sqlite3_column_name().

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

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

• Приложение должно гарантировать, что первый параметр функции sqlite3_exec() является валидным и открытым соединением с базой данных.
• Приложение не должно закрывать соединение с базой данных, указанное первым параметром функции sqlite3_exec(), пока выполняется sqlite3_exec().
• Приложение не должно изменять текст SQL-запроса, переданный во второй параметр функции 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 не регистрируются. Если в соединении с базой данных D никогда не было успешных INSERT в таблицы с rowid, то sqlite3_last_insert_rowid(D) возвращает ноль.

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

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

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

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 PRAGMA.

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

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

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-инъекции, которые могут дать злоумышленникам доступ к возможностям загрузки расширений.

См. также функцию SQL 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. Пример использования этого интерфейса – обновление пользовательского интерфейса во время выполнения большого запроса.

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

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

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

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

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

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

void sqlite3_randomness(int N, void *P);

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

Вызов этой процедуры сохраняет N байтов случайности в буфер P. Параметр P может быть указателем NULL.

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

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

int sqlite3_release_memory(int);

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

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

Сброс объекта подготовленного оператора

int sqlite3_reset(sqlite3_stmt *pStmt);

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

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

Код возврата из sqlite3_reset(S) указывает, завершилось ли предыдущее выполнение подготовленного оператора S успешно. Если sqlite3_step(S) никогда ранее не вызывался для S или если sqlite3_step(S) не вызывался с момента предыдущего вызова 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.

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

Если SQLite скомпилирован с -DSQLITE_STRICT_SUBTYPE=1, то любая SQL-функция, которая вызывает интерфейс sqlite3_result_subtype() и не имеет свойства SQLITE_RESULT_SUBTYPE, вызовет ошибку. Будущие версии SQLite могут включить -DSQLITE_STRICT_SUBTYPE=1 по умолчанию.

Сериализация базы данных

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.

Установка значения последнего вставленного ряда.

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 и операционной системы. Некоторые системы рассматривают отрицательный аргумент как команду спать вечно. Другие понимают это как команду не спать вообще. В версии SQLite 3.42.0 и более поздних версиях отрицательный аргумент, переданный в sqlite3_sleep(), изменяется на ноль перед передачей в метод xSleep VFS.

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

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

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

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

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

В противном случае этот 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 не определено.

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

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

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

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

Функция также может вернуть SQLITE_NOMEM. Если она вызвана с обработчиком базы данных в режиме автоматического подтверждения, но завершается неудачно по другой причине, состояние открытой транзакции чтения в схеме 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 при успехе или соответствующий код ошибки при неудаче.

Для успеха подключение к базе данных не должно находиться в режиме автоматического подтверждения при вызове sqlite3_snapshot_open(D,S,P). Если уже открыта транзакция чтения в схеме S, то обработчик базы данных не должен иметь активных операторов (запросы SELECT, которые были переданы в 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, если не было предварительных операций ввода-вывода с этим подключением или если база данных перешла в режим WAL после последних операций ввода-вывода с этим подключением. (Подсказка: Запустите "PRAGMA application_id" против недавно открытого подключения к базе данных, чтобы подготовить его к использованию снимков.)

Интерфейс sqlite3_snapshot_open() доступен только при использовании опции компиляции SQLITE_ENABLE_SNAPSHOT.

Восстановление снимков из файла журнала

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

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

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

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

Этот интерфейс доступен только в случае, если 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() не следует вызывать повторно на виртуальной машине. Дополнительную информацию можно получить, вызвав 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(). Но после версии 3.6.23.1 (26 марта 2010 г.) sqlite3_step() начал автоматически вызывать sqlite3_reset() в этой ситуации вместо возврата SQLITE_MISUSE. Это не считается нарушением совместимости, так как любое приложение, получившее ошибку SQLITE_MISUSE, по определению некорректно. Опция компиляции SQLITE_OMIT_AUTORESET может быть использована для восстановления устаревшего поведения.

ВНИМАНИЕ: Устаревший интерфейс: В устаревшем интерфейсе API sqlite3_step() всегда возвращает общий код ошибки 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 (ненулевое значение), если подготовленный запрос 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 для подготовленного запроса S. Если E равно нулю, то 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 изменить не удалось. Режим 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 (ненулевое значение), если и только если подготовленный запрос X не вносит прямых изменений в содержимое файла базы данных.

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

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

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

Операторы управления транзакциями, такие как BEGIN, COMMIT, ROLLBACK, SAVEPOINT и RELEASE, вызывают возвращение true от sqlite3_stmt_readonly(), так как сами операторы фактически не изменяют базу данных, а контролируют время, когда другие операторы изменяют базу данных. Операторы ATTACH и DETACH также вызывают возвращение true от sqlite3_stmt_readonly(), поскольку, хотя эти операторы изменяют конфигурацию соединения с базой данных, они не вносят изменения в содержимое файлов базы данных на диске. Интерфейс 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 с символом экранирования E. Определение соответствия шаблону LIKE, используемое в sqlite3_strlike(P,X,E), совпадает с оператором "X LIKE P ESCAPE E" в диалекте SQL, понимаемом 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-символы преобразуются в одинаковый регистр.

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

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

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

int sqlite3_system_errno(sqlite3*);

Попытка вернуть базовый код или номер ошибки операционной системы, вызвавший последнюю ошибку ввода-вывода или неудачу при открытии файла. Возвращаемое значение зависит от ОС. Например, в системах 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, все присоединённые базы данных проверяются по тому же алгоритму, который используется движком базы данных для разрешения неквалифицированных ссылок на таблицы.

Третий и четвёртый параметры этой функции — имя таблицы и имя столбца желаемого столбца соответственно.

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

Параметр	Тип вывода	Описание
5-й	const char*	Тип данных
6-й	const char*	Имя последовательности сортировки по умолчанию
7-й	int	Истина, если столбец имеет ограничение NOT NULL
8-й	int	Истина, если столбец является частью PRIMARY KEY
9-й	int	Истина, если столбец 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 был скомпилирован без кода блокировки из-за того, что опция компиляции SQLITE_THREADSAFE была установлена в 0.

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

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

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

Этот интерфейс только сообщает о значении установки мьютексов на этапе компиляции флага SQLITE_THREADSAFE. Если SQLite скомпилирован с SQLITE_THREADSAFE=1 или =2, то мьютексы по умолчанию включены, но могут быть полностью или частично отключены с помощью вызова 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 равна нулю, то трассировка отключена. Аргумент M должен быть результатом побитового ИЛИ комбинации нуля или более констант 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, если необходимые блокировки в общей кэш-памяти или отдельных таблицах в общей кэш-памяти не могут быть получены. Подробное описание блокировок в режиме общей кэш-памяти см. в разделе Режим общей кэш-памяти SQLite. Этот API можно использовать для регистрации функции обратного вызова, которую SQLite вызовет, когда соединение, в настоящее время удерживающее необходимую блокировку, освободит ее. Этот API доступен только в том случае, если библиотека была скомпилирована с определенным препроцессором C-символом SQLITE_ENABLE_UNLOCK_NOTIFY.

См. также: Использование функции уведомления об отпирании SQLite.

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

Когда соединение (известное как заблокированное соединение) не может получить блокировку общей кэш-памяти и вызывающему лицу возвращается 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*, а второй — количество элементов в массиве.

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

Обнаружение тупика

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

Чтобы избежать этой ситуации, функция sqlite3_unlock_notify() выполняет обнаружение тупика. Если данный вызов sqlite3_unlock_notify() приведет к тупику в системе, то возвращается SQLITE_LOCKED, и никакая функция обратного вызова отпирания не регистрируется. Система считается находящейся в тупике, если соединение A зарегистрировало функцию обратного вызова отпирания при завершении транзакции соединения B, а соединение B само зарегистрировало функцию обратного вызова отпирания при завершении транзакции соединения A. Обнаружение косвенного тупика также разрешено, поэтому система также считается находящейся в тупике, если соединение 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() регистрирует функцию обратного вызова в соединении с базой данных, идентифицированном первым аргументом, которая вызывается всякий раз, когда строка обновляется, вставляется или удаляется в таблице с порядковым индексом. Любой обратный вызов, установленный предыдущим вызовом этой функции для того же соединения с базой данных, переопределяется.

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

Функция обратного вызова обновления не вызывается при изменении внутренних системных таблиц (т.е. sqlite_sequence). Функция обратного вызова обновления не вызывается при изменении таблиц WITHOUT ROWID.

В текущей реализации функция обратного вызова обновления не вызывается, когда конфликтующие строки удаляются из-за ON CONFLICT REPLACE. Аналогично, функция обратного вызова обновления не вызывается, когда строки удаляются с помощью оптимизации усечения. Исключение, указанные в этом абзаце, могут измениться в будущей версии 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 (пятым параметром) процедур 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. Обычным приложениям не нужно знать, каково внутреннее состояние объекта sqlite3_value, и поэтому им не нужно использовать этот интерфейс.

Определение подтипа значений SQL

unsigned int sqlite3_value_subtype(sqlite3_value*);

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

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

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

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", находятся рядом.

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

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

Следующая таблица обобщает условия, при которых виртуальная таблица разрешена для установки флага "orderByConsumed" в зависимости от значения, возвращённого sqlite3_vtab_distinct(). Эта таблица является переформулировкой предыдущих четырёх абзацев:

Для целей сравнения значений вывода виртуальной таблицы для определения того, являются ли значения одинаковыми для целей сортировки, два значения 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() реализации виртуальной таблицы. Результат вызова этого интерфейса в любом другом контексте не определён и, вероятно, вреден.

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

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

1. Вызов sqlite3_vtab_in(P,N,-1) вернет значение true (не ноль), если и только если ограничение 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 (не ноль), это означает, что ограничение является оператором IN, который можно обработать сразу. Если ограничение не является оператором IN или не может быть обработано сразу, интерфейс возвращает false.

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

1. Значение P->aConstraintUsage[N].argvIndex установлено в положительное целое число. Таким образом, виртуальная таблица сообщает 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(). В этом случае 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 реализации виртуальной таблицы для операции INSERT или UPDATE. Возвращаемое значение — это одно из значений 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. Если правой операнд — это выражение или ссылка на другой столбец или параметр хоста, то sqlite3_vtab_rhs_value() скорее всего вернёт SQLITE_NOTFOUND.

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

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

"_rhs_" в имени этой процедуры — это аббревиатура от «Правой части».

Настройка автоматической точки проверки

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 может использоваться для вызова этого интерфейса из SQL.

Точки проверки, инициированные этим механизмом, являются ПАССИВНЫМИ.

Каждое новое подключение базы данных по умолчанию имеет включенную автоматическую точку проверки с порогом в 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 в файл базы данных и сбрасывает журнал предварительной записи. Дополнительную информацию см. в документации по точкам проверки.

Этот интерфейс раньше был единственным способом инициирования точки проверки. Но затем был добавлен более новый и мощный интерфейс 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 никогда не вызывается в режиме SQLITE_CHECKPOINT_PASSIVE. С другой стороны, пассивный режим может оставить точку проверки незавершенной, если существуют одновременные операции чтения или записи.

SQLITE_CHECKPOINT_FULL

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

SQLITE_CHECKPOINT_RESTART

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

SQLITE_CHECKPOINT_TRUNCATE

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

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

Все вызовы получают эксклюзивную «точку проверки» блокировку файла базы данных. Если любой другой процесс выполняет операцию точки проверки в то же время, блокировка не может быть получена, и возвращается 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.

Если интерфейс sqlite3_wal_checkpoint_v2() не возвращает SQLITE_MISUSE, он устанавливает информацию об ошибке, к которой обращаются 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() и pragma wal_autocheckpoint оба вызывают 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 */

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

Эти целочисленные константы могут использоваться в качестве третьего параметра метода 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-операторов. Второй параметр обратного вызова — целочисленный код, который определяет действие, подлежащее авторизации. Вот целочисленные коды действий, которые может получить функция обратного вызова авторизатора.

Эти значения кодов действий означают, какой тип операции нужно авторизовать. Третий и четвёртый параметры функции обратного вызова авторизации будут параметрами или NULL в зависимости от того, какой из этих кодов используется в качестве второго параметра. Пятый параметр функции обратного вызова авторизатора — имя базы данных («main», «temp» и т. д.), если применимо. Шестой параметр функции обратного вызова авторизатора — имя внутреннего триггера или представления, ответственного за попытку доступа, или 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-битное знаковое целое число
• 64-битное число с плавающей точкой IEEE
• строка
• BLOB
• NULL

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

Обратите внимание, что константа SQLITE_TEXT также использовалась в SQLite версии 2 для совершенно другого значения. Программное обеспечение, которое подключается как к SQLite версии 2, так и к SQLite версии 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(). См. документацию 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 */
#define SQLITE_CONFIG_ROWID_IN_VIEW       30  /* int* */

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

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

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

• SQLITE_CONFIG_LOG
• SQLITE_CONFIG_PCACHE_HDRSZ

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

SQLITE_CONFIG_SINGLETHREAD

Для этого параметра нет аргументов. Этот параметр устанавливает режим работы потоков (режим потоков) в значение «Один поток». Другими словами, он отключает все мьютексы и переводит SQLite в режим, где его может использовать только один поток. Если SQLite скомпилирован с параметром компиляции SQLITE_THREADSAFE=0, то изменить режим работы потоков (режим потоков) с его значения по умолчанию «Один поток» невозможно, и вызов sqlite3_config() с параметром конфигурации SQLITE_CONFIG_SINGLETHREAD вернёт SQLITE_ERROR.

SQLITE_CONFIG_MULTITHREAD

Для этого параметра нет аргументов. Этот параметр устанавливает режим работы потоков (режим потоков) в значение «Многопоточный». Другими словами, он отключает мьютексы для объектов соединения с базой данных (соединения с базой данных) и подготовленных запросов (подготовленные запросы). Приложение отвечает за сериализацию доступа к соединениям с базой данных (соединениям с базами данных) и подготовленным запросам (подготовленным заявлениям). Однако другие мьютексы включены, что делает SQLite безопасным для использования в многопоточной среде, пока никакие два потока не пытаются использовать одно и то же соединение с базой данных (соединение с базой данных) одновременно. Если SQLite скомпилирован с параметром компиляции SQLITE_THREADSAFE=0, то установить многопоточный (режим потоков) режим невозможно, и вызов sqlite3_config() с параметром конфигурации SQLITE_CONFIG_MULTITHREAD вернёт SQLITE_ERROR.

SQLITE_CONFIG_SERIALIZED

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

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, интерпретируемый как булево значение. Если оно истинно, SQLite получает подсказку, что следует избегать больших выделений памяти, если это возможно. SQLite будет работать быстрее, если ему разрешено выполнять большие выделения памяти, но некоторые приложения могут предпочесть более медленную работу в обмен на гарантии по поводу фрагментации памяти, которая возможна при избегании больших выделений. Эта подсказка по умолчанию отключена.

SQLITE_CONFIG_MEMSTATUS

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

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

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

SQLITE_CONFIG_SCRATCH

Параметр SQLITE_CONFIG_SCRATCH больше не используется.

SQLITE_CONFIG_PAGECACHE

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

SQLITE_CONFIG_HEAP

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

SQLITE_CONFIG_MUTEX

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

SQLITE_CONFIG_GETMUTEX

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

SQLITE_CONFIG_LOOKASIDE

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

SQLITE_CONFIG_PCACHE2

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

SQLITE_CONFIG_GETPCACHE2

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

SQLITE_CONFIG_LOG

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

SQLITE_CONFIG_URI

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

SQLITE_CONFIG_COVERING_INDEX_SCAN

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

SQLITE_CONFIG_PCACHE и SQLITE_CONFIG_GETPCACHE

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

SQLITE_CONFIG_SQLLOG

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

SQLITE_CONFIG_MMAP_SIZE

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

SQLITE_CONFIG_WIN32_HEAPSIZE

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

SQLITE_CONFIG_PCACHE_HDRSZ

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

SQLITE_CONFIG_PMASZ

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

SQLITE_CONFIG_STMTJRNL_SPILL

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

SQLITE_CONFIG_SORTERREF_SIZE

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

SQLITE_CONFIG_MEMDB_MAXSIZE

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

SQLITE_CONFIG_ROWID_IN_VIEW

Параметр SQLITE_CONFIG_ROWID_IN_VIEW включает или отключает возможность для представлений иметь ROWID. Возможность может быть включена только в том случае, если SQLite скомпилирован с -DSQLITE_ALLOW_ROWID_IN_VIEW, в этом случае возможность включена по умолчанию. Этот параметр конфигурации запрашивает текущее значение или изменяет его на «выключено» или «включено». Аргументом является указатель на целое число. Если это целое число изначально имеет значение 1, то возможность для представлений иметь ROWID активируется. Если целое число изначально имеет значение ноль, то возможность отключается. Любое другое начальное значение целого числа оставляет настройку без изменений. После изменений (если таковые имеются), целое число записывается со значением 1 или 0, если возможность для представлений иметь ROWID включена или выключена. Если SQLite скомпилирован без -DSQLITE_ALLOW_ROWID_IN_VIEW (что является обычным и рекомендуемым случаем), то целое число всегда заполняется нулём, независимо от его начального значения.

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

#define SQLITE_DBCONFIG_MAINDBNAME            1000 /* const char* */
#define SQLITE_DBCONFIG_LOOKASIDE             1001 /* void* int int */
#define SQLITE_DBCONFIG_ENABLE_FKEY           1002 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_TRIGGER        1003 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE      1006 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_QPSG           1007 /* int int* */
#define SQLITE_DBCONFIG_TRIGGER_EQP           1008 /* int int* */
#define SQLITE_DBCONFIG_RESET_DATABASE        1009 /* int int* */
#define SQLITE_DBCONFIG_DEFENSIVE             1010 /* int int* */
#define SQLITE_DBCONFIG_WRITABLE_SCHEMA       1011 /* int int* */
#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE    1012 /* int int* */
#define SQLITE_DBCONFIG_DQS_DML               1013 /* int int* */
#define SQLITE_DBCONFIG_DQS_DDL               1014 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_VIEW           1015 /* int int* */
#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT    1016 /* int int* */
#define SQLITE_DBCONFIG_TRUSTED_SCHEMA        1017 /* int int* */
#define SQLITE_DBCONFIG_STMT_SCANSTATUS       1018 /* int int* */
#define SQLITE_DBCONFIG_REVERSE_SCANORDER     1019 /* int int* */
#define SQLITE_DBCONFIG_MAX                   1019 /* Largest DBCONFIG */

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

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

SQLITE_DBCONFIG_LOOKASIDE

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

SQLITE_DBCONFIG_ENABLE_FKEY

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

SQLITE_DBCONFIG_ENABLE_TRIGGER

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

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

SQLITE_DBCONFIG_ENABLE_VIEW

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

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

SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

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

SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

Этот параметр используется для включения или выключения интерфейса sqlite3_load_extension() независимо от SQL-функции load_extension(). API sqlite3_enable_load_extension() включает или выключает как C-API sqlite3_load_extension(), так и SQL-функцию load_extension(). Должны быть два дополнительных аргумента. Если первый аргумент этого интерфейса равен 1, то включен только C-API, а SQL-функция остается отключенной. Если первый аргумент этого интерфейса равен 0, то отключены как C-API, так и SQL-функция. Если первый аргумент равен -1, то изменения не вносятся ни в C-API, ни в SQL-функцию. Второй параметр — указатель на целое число, в которое записывается 0 или 1, чтобы указать, отключен или включен интерфейс sqlite3_load_extension() после вызова. Второй параметр может быть указателем NULL, в этом случае новая настройка не будет сообщена.

SQLITE_DBCONFIG_MAINDBNAME

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

SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

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

SQLITE_DBCONFIG_ENABLE_QPSG

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

SQLITE_DBCONFIG_TRIGGER_EQP

По умолчанию вывод команд EXPLAIN QUERY PLAN не включает вывод для любых операций, выполняемых программами триггеров. Этот параметр используется для установки или сброса (по умолчанию) флага, который регулирует это поведение. Первый параметр, переданный в эту операцию, — целое число: положительное значение для включения вывода для программ триггеров, ноль для его отключения или отрицательное значение для сохранения текущих настроек. Второй параметр — указатель на целое число, в которое записывается 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, заставляя её работать так, как это было до версии 3.24.0 (2018-06-04). Дополнительную информацию см. в разделе "Замечания по совместимости" в документации ALTER TABLE RENAME. Эту функцию также можно включить и выключить с помощью команды PRAGMA legacy_alter_table.

SQLITE_DBCONFIG_DQS_DML

Опция SQLITE_DBCONFIG_DQS_DML активирует или деактивирует устаревшую особенность двойных кавычек в строковых литералах только для команд DML, то есть DELETE, INSERT, SELECT и UPDATE. Значение по умолчанию этой настройки определяется параметром компиляции -DSQLITE_DQS.

SQLITE_DBCONFIG_DQS_DDL

Опция SQLITE_DBCONFIG_DQS активирует или деактивирует устаревшую особенность двойных кавычек в строковых литералах для команд DDL, таких как CREATE TABLE и CREATE INDEX. Значение по умолчанию этой настройки определяется параметром компиляции -DSQLITE_DQS.

SQLITE_DBCONFIG_TRUSTED_SCHEMA

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

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

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

SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

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

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

SQLITE_DBCONFIG_STMT_SCANSTATUS

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

SQLITE_DBCONFIG_REVERSE_SCANORDER

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

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

#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
#define SQLITE_RESULT_SUBTYPE   0x001000000
#define SQLITE_SELFORDER1       0x002000000

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

SQLITE_DETERMINISTIC

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

SQLITE_DIRECTONLY

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

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

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

SQLITE_INNOCUOUS

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

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

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

SQLITE_SUBTYPE

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

SQLITE_RESULT_SUBTYPE

Флаг SQLITE_RESULT_SUBTYPE указывает SQLite, что функция может вызвать sqlite3_result_subtype(), чтобы связать подтип со своим результатом. Каждая функция, вызывающая sqlite3_result_subtype(), должна иметь этот флаг. В противном случае вызов sqlite3_result_subtype() может стать пустой операцией, если функция используется как элемент в индексе выражений. С другой стороны, SQL-функции, которые никогда не вызывают sqlite3_result_subtype(), должны избегать установки этого свойства, так как его назначение заключается в отключении определённых оптимизаций, несовместимых с подтипами.

SQLITE_SELFORDER1

Флаг SQLITE_SELFORDER1 указывает, что функция является агрегатной, которая внутренне упорядочивает значения, предоставляемые первому аргументу. Для вызова этой функции можно использовать обозначение SQL агрегата упорядоченного множества с единственным членом ORDER BY. Если для функции, которой не хватает этого флага, используется обозначение агрегата упорядоченного множества, возникает ошибка. Обратите внимание, что синтаксис агрегата упорядоченного множества доступен только в том случае, если SQLite скомпилирован с опцией времени компиляции -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES.

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

#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 используется для запроса расширения и обрезки файла базы данных кусками заданного пользователем размера. Четвёртый аргумент sqlite3_file_control() должен указывать на целое число (тип int), содержащее новый размер куска для использования в базе данных. Выделение места в файле базы данных большими кусками (например, по 1 МБ за раз) может уменьшить фрагментацию файловой системы и улучшить производительность на некоторых системах.

• Код 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. Однако, если база данных синхронизируется как часть многобазового подтверждения, аргумент указывает на строку с нулевым окончанием, содержащую имя файла супер-журнала транзакций. VFS, которым не нужен этот сигнал, должны беспрепятственно игнорировать этот код. Приложения не должны вызывать sqlite3_file_control() с этим кодом, так как это может нарушить работу специализированных VFS, которым он нужен.

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

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

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

• Код 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 может использоваться для получения имен всех VFS в стеке VFS. Имена всех VFS-платформ и конечного VFS-слоя записываются в память, полученную из sqlite3_malloc(), и результат хранится в переменной char*, на которую указывает четвёртый параметр sqlite3_file_control(). Вызывающая сторона отвечает за освобождение памяти по окончании работы. Как и во всех действиях управления файлами, нет гарантии, что это что-то сделает. Вызывающие стороны должны инициализировать переменную char* нулевым указателем на случай, если это управление файлами не реализовано. Это управление файлами предназначено только для диагностики.

• Код 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 или сообщением об ошибке в случае неудачи. Если управление файлами 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 сгенерировал временное имя файла, используя тот же алгоритм, что и для генерации временных имён файлов для временных таблиц и других внутренних целей. Аргументом должна быть строка char**, которая будет заполнена именем файла, записанным в память, полученную из sqlite3_malloc(). Вызывающий код должен вызвать sqlite3_free() для результата, чтобы избежать утечки памяти.

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

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

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

• Код 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, то дескриптор файла переходит в «режим пакетной записи», что означает, что все последующие операции записи будут отложены и выполнены атомарно при следующем вызове 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 используется только внутри шима VFS проверки контрольной суммы.

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

Коды операторов ограничений виртуальной таблицы

#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_INDEX_SCAN_UNIQUE 0x00000001 /* Scan visits at most 1 row */
#define SQLITE_INDEX_SCAN_HEX    0x00000002 /* Display idxNum as hex */
                                            /* in EXPLAIN QUERY PLAN */

Реализации виртуальных таблиц могут устанавливать поле sqlite3_index_info.idxFlags в некоторое сочетание этих битов.

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

#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 возвращает целое число, которое представляет собой вектор этих битовых значений, выражающих характеристики ввода-вывода устройства хранения данных, на котором находится файл, на который ссылается объект 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.

Типы мьютексов

#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() принимает единственный аргумент, который является одним из этих целочисленных констант.

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

Флаги для операций открытия файла

#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 */

Эти битовые значения предназначены для использования в третьем параметре интерфейса sqlite3_open_v2() и в четвёртом параметре метода sqlite3_vfs.xOpen.

Только те флаги, помеченные как «Подходят для 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

Целочисленная переменная по указателю V будет установлена в идентификатор для X-го элемента плана запроса. Идентификатор уникален в пределах выражения. Значение select-id совпадает со значением в первой колонке запроса EXPLAIN QUERY PLAN.

SQLITE_SCANSTAT_PARENTID

Переменная типа "int" по указателю V будет установлена в идентификатор родительского элемента текущего элемента плана запроса, если применимо, или в ноль, если элемент плана запроса не имеет родителя. Это то же значение, что возвращается во второй колонке запроса 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.47.0"
#define SQLITE_VERSION_NUMBER 3047000
#define SQLITE_SOURCE_ID      "2024-10-21 16:30:22 03a9703e27c44437c39363d0baf82db4ebc94538a0f28411c85dda156f82636e"

Препроцессорная макрокоманда 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 будет сброшен к нулю.

Начиная с версии 3.6.18 (2009-09-11), исходный код SQLite хранится в системе управления версиями Fossil. Макрокоманда 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 должно создать свою собственную частную копию содержимого перед возвратом.

Этот typedef необходим для работы с проблемами в некоторых компиляторах 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() (или их внутренние эквиваленты). Интересно только значение, возвращаемое в параметре *pHighwater функции sqlite3_status(). Значение, записанное в *pCurrent, не определено.

SQLITE_STATUS_MALLOC_COUNT

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

SQLITE_STATUS_PAGECACHE_USED

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

SQLITE_STATUS_PAGECACHE_OVERFLOW

Этот параметр возвращает количество байтов выделения кэша страниц, которые не смогли быть удовлетворены буфером SQLITE_CONFIG_PAGECACHE и были вынуждены перейти во sqlite3_malloc(). Возвращаемое значение включает выделения, которые переполнились, потому что они были слишком большими (они были больше, чем параметр «sz» в SQLITE_CONFIG_PAGECACHE), и выделения, которые переполнились, потому что в кэше страниц не осталось места.

SQLITE_STATUS_PAGECACHE_SIZE

Этот параметр записывает самый большой запрос на выделение памяти, переданный механизму выделения памяти pagecache. Интересно только значение, возвращаемое в параметре *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, это означает, что операция синхронизации должна только сбросить данные в постоянную память. Информация о узле не должна сбрасываться. Если младшие четыре бита флага равны SQLITE_SYNC_NORMAL, это означает использование семантики обычного fsync(). Если младшие четыре бита равны SQLITE_SYNC_FULL, это означает использование синхронизации в стиле Mac OS X вместо fsync().

Не путайте флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL с настройками PRAGMA synchronous=NORMAL и PRAGMA synchronous=FULL. Предикат synchronous pragma определяет, когда выполняются вызовы метода xSync VFS, и применяется одинаково на всех платформах. Флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL определяют, насколько энергичной или строгой или сильной будет операция синхронизации, и имеют значение только для Mac OSX в стандартном коде SQLite. (Реализации VFS сторонних разработчиков также могут различать SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL, но из поддерживаемых операционных систем только 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_JSON_SELFCHECK          14
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
#define SQLITE_TESTCTRL_ISKEYWORD               16  /* NOT USED */
#define SQLITE_TESTCTRL_GETOPT                  16
#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  /* NOT USED */
#define SQLITE_TESTCTRL_LAST                    34  /* Largest TESTCTRL */

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

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

Коды событий трассировки SQL

#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) — это результат побитового ИЛИ одного или нескольких из следующих констант. Первый аргумент обратного вызова трассировки — одна из следующих констант.

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

Обратный вызов трассировки имеет четыре аргумента: xCallback(T,C,P,X). Аргумент T — один из целочисленных типов кодов выше. Аргумент C — копия указателя на контекст, переданного в качестве четвёртого аргумента sqlite3_trace_v2(). Аргументы P и X — указатели, значение которых зависит от T.

SQLITE_TRACE_STMT

Обратный вызов SQLITE_TRACE_STMT вызывается, когда подготовленный запрос впервые начинает выполняться, и, возможно, в другие моменты во время выполнения подготовленного запроса, например, в начале каждого подпрограммы триггера. Аргумент P — указатель на подготовленный запрос. Аргумент X — указатель на строку, которая представляет собой необработанный текст SQL подготовленного запроса или комментарий SQL, указывающий вызов триггера. Обратный вызов может вычислить ту же строку, что и возвращался бы legacy интерфейс sqlite3_trace(), используя аргумент X, если X начинается с "--", и вызывая sqlite3_expanded_sql(P) в противном случае.

SQLITE_TRACE_PROFILE

Обратный вызов SQLITE_TRACE_PROFILE предоставляет примерно ту же информацию, что и обратный вызов sqlite3_profile(). Аргумент P — указатель на подготовленный запрос, а аргумент X указывает на 64-битное целое число, которое приблизительно равно числу наносекунд, потраченных подготовленным запросом на выполнение. Обратный вызов 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) внутри методов xConnect или xCreate реализации виртуальной таблицы инструктируют планировщик запросов начинать как минимум транзакцию чтения на всех схемах («main», «temp» и любых подключенных базах данных) всякий раз, когда используется виртуальная таблица.

Типы каталогов Win32

#define SQLITE_WIN32_DATA_DIRECTORY_TYPE  1
#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  2

Эти макросы доступны только на Windows. Они определяют разрешённые значения аргумента type для интерфейса 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.

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

Максимальное количество инструкций в программе виртуальной машины, используемой для реализации SQL-запроса. Если sqlite3_prepare_v2() или эквивалент пытается выделить память для более чем этого количества кодов операций в одном подготовленном запросе, возвращается ошибка SQLITE_NOMEM.

SQLITE_LIMIT_FUNCTION_ARG

Максимальное количество аргументов функции.

SQLITE_LIMIT_ATTACHED

Максимальное количество подключенных баз данных.

SQLITE_LIMIT_LIKE_PATTERN_LENGTH

Максимальная длина аргумента pattern для операторов 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

Этот параметр возвращает количество слотов кэша lookaside, которые в данный момент заняты.

SQLITE_DBSTATUS_LOOKASIDE_HIT

Этот параметр возвращает количество попыток malloc, которые были удовлетворены с помощью кэша lookaside. Значимым является только максимальное значение; текущее значение всегда равно нулю.

SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE

Этот параметр возвращает количество попыток malloc, которые могли бы быть удовлетворены с помощью кэша lookaside, но потерпели неудачу из-за того, что запрашиваемый объем памяти был больше размера слота lookaside. Значимым является только максимальное значение; текущее значение всегда равно нулю.

SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL

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

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

Этот параметр возвращает приблизительное количество байтов оперативной памяти, используемой для хранения схемы всех баз данных, связанных с подключением — основной, временной и любых баз данных, подключенных с помощью ATTACH. Полный объем используемой памяти схем сообщается, даже если память схемы используется совместно с другими подключениями к базе данных из-за включенного режима совместного кэширования. Максимальное значение, связанное с SQLITE_DBSTATUS_SCHEMA_USED, всегда равно 0.

SQLITE_DBSTATUS_STMT_USED

Этот параметр возвращает приблизительное количество байтов оперативной памяти и памяти lookaside, используемых всеми подготовленными запросами, связанными с подключением к базе данных. Максимальное значение, связанное с 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, или количество страниц, записанных в файл базы данных в режиме отката. Любые страницы, записанные в рамках операций отката транзакции или восстановления базы данных, не включаются. Если при записи страницы на диск возникает ошибка ввода-вывода или другая ошибка, влияние на последующие запросы 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 вернул «не найдено». Соответствующее значение SQLITE_STMTSTATUS_FILTER_MISS — это количество раз, когда фильтр Bloom вернул «найдено», и поэтому этап объединения должен был быть обработан как обычно.

SQLITE_STMTSTATUS_MEMUSED

Это приблизительное количество байтов оперативной памяти, используемой для хранения подготовленного запроса. Это значение фактически не является счётчиком, поэтому параметр resetFlg в sqlite3_stmt_status() игнорируется, когда opcode равен 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-битные целочисленные типы

#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-битных целых беззнаковых и со знаком.

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. Курсоры используются методами модуля xFilter, xNext, xEof, xColumn и xRowid. Каждая реализация модуля определит содержимое структуры курсора в соответствии со своими потребностями.

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

Обработка открытого BLOB

typedef struct sqlite3_blob sqlite3_blob;

Экземпляр этого объекта представляет собой открытый BLOB, над которым можно выполнять постепенный ввод-вывод BLOB. Объекты этого типа создаются с помощью 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()

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

• 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_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_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 всегда будет степенью двойки. Второй параметр szExtra — это количество байтов дополнительного хранилища, связанного с каждой записью кэша страниц. Параметр szExtra будет числом меньше 250. SQLite будет использовать дополнительные szExtra байты на каждой странице для хранения метаданных о соответствующей странице базы данных на диске. Передаваемое значение szExtra зависит от версии SQLite, целевой платформы и того, как SQLite был скомпилирован. Третий аргумент xCreate(), bPurgeable, равен true, если создаваемый кэш будет использоваться для кэширования страниц базы данных файла, хранящегося на диске, или false, если он используется для базы данных в оперативной памяти. Реализации кэша не нужно делать ничего особенного в зависимости от значения bPurgeable; оно является только рекомендацией. В кэше, где bPurgeable равен false, SQLite никогда не вызовет xUnpin(), за исключением преднамеренного удаления страницы. Другими словами, вызовы xUnpin() в кэше с bPurgeable, установленным в false, всегда будут иметь флаг «удаление» (discard) установленным в true. Следовательно, кэш, созданный с bPurgeable, равным false, никогда не будет содержать каких-либо неподкреплённых страниц.

Метод xCachesize() может быть вызван SQLite в любое время для установки рекомендуемого максимального размера кэша (количества страниц, хранящихся в) экземпляре кэша, переданном в качестве первого аргумента. Это значение настраивается с помощью команды SQLite "PRAGMA cache_size". Как и параметр bPurgeable, реализация не обязана выполнять какие-либо действия с этим значением; оно является только рекомендацией.

Метод xPagecount() должен возвращать количество страниц, хранящихся в кэше в данный момент, как закреплённых (pinned), так и незакреплённых (unpinned).

Метод xFetch() ищет страницу в кэше и возвращает указатель на объект sqlite3_pcache_page, связанный с этой страницей, или нулевой указатель. Элемент pBuf возвращаемого объекта sqlite3_pcache_page будет указателем на буфер размером szPage байтов, используемый для хранения содержимого одной страницы базы данных. Элемент pExtra объекта sqlite3_pcache_page будет указателем на szExtra байты дополнительного хранилища, запрошенные SQLite для каждой записи в кэше страниц.

Страница, которая должна быть извлечена, определяется ключом. Минимальное значение ключа — 1. После извлечения с помощью xFetch страница считается «закреплённой» (pinned).

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

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

SQLite обычно вызывает xFetch() с createFlag 0 или 1. SQLite будет использовать createFlag 2 только после того, как предыдущий вызов с createFlag 1 завершился неудачно. Между вызовами xFetch() SQLite может попытаться снять закрепление с одной или нескольких страниц кэша, выгрузив содержимое закреплённых страниц на диск и синхронизировав кэш диска операционной системы.

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

Кэш не должен выполнять подсчёт ссылок. Один вызов xUnpin() снимает закрепление с страницы независимо от количества предыдущих вызовов xFetch().

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

Когда 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 может быть «защищённым» или «незащищённым». Некоторые интерфейсы требуют защищённый sqlite3_value. Другие интерфейсы принимают как защищённый, так и незащищённый sqlite3_value. Каждый интерфейс, принимающий аргументы sqlite3_value, указывает, требует ли он защищённый sqlite3_value. Интерфейс sqlite3_value_dup() может быть использован для создания нового защищённого sqlite3_value из незащищённого sqlite3_value.

Термины «защищённый» и «незащищённый» относятся к тому, захвачен ли мьютекс. Внутренний мьютекс захвачен для защищённого объекта sqlite3_value, но мьютекс не захвачен для незащищённого объекта sqlite3_value. Если SQLite скомпилирован для однопоточной работы (с SQLITE_THREADSAFE=0 и sqlite3_threadsafe() возвращает 0) или если SQLite работает в одном из режимов с уменьшенными мьютексами 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

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

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 резервного копирования копирует содержимое одной базы данных в другую. Это полезно для создания резервных копий баз данных или для копирования баз данных в памяти в постоянные файлы или из них.

См. также: Использование API резервного копирования SQLite в режиме онлайн

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() не может получить необходимый системный замок, то вызывается функция обработчика занятости (если она задана). Если обработчик занятости возвращает ненулевое значение до того, как замок станет доступен, то возвращается 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(), независимо от того, завершился ли sqlite3_backup_step() или нет. Если во время любого предыдущего вызова 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 в настоящее время не проверяет, не обращается ли приложение некорректно к целевому соединению с базой данных, поэтому код ошибки не сообщается, но операции всё же могут работать неправильно. Использование целевого соединения с базой данных во время резервного копирования также может привести к тупику мьютекса.

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

Объект sqlite3_backup сам по себе частично потокобезопасен. Несколько потоков могут безопасно выполнять несколько одновременных вызовов sqlite3_backup_step(). Однако API sqlite3_backup_remaining() и sqlite3_backup_pagecount() не являются строго говоря потокобезопасными. Если они вызываются одновременно с другим потоком, вызывающим sqlite3_backup_step(), возможно, что они вернут недопустимые значения.

Альтернативы использованию API резервного копирования

Другие методы для безопасного создания согласованной резервной копии базы данных SQLite включают:

• Команда VACUUM INTO.
• Утилита sqlite3_rsync.

Подсчёт количества изменённых строк

int sqlite3_changes(sqlite3*);
sqlite3_int64 sqlite3_changes64(sqlite3*);

Эти функции возвращают количество строк, изменённых, вставленных или удалённых последним выполненным оператором INSERT, UPDATE или DELETE в соединении с базой данных, указанном в единственном параметре. Эти две функции идентичны, за исключением типа возвращаемого значения и того, что если количество изменённых строк последним оператором INSERT, UPDATE или DELETE больше максимального значения, поддерживаемого типом «int», то возвращаемое значение sqlite3_changes() неопределённо. Выполнение любого другого типа SQL-запроса не изменяет значение, возвращаемое этими функциями.

Рассматриваются только изменения, внесённые непосредственно оператором INSERT, UPDATE или DELETE — вспомогательные изменения, вызванные триггерами, действиями с внешними ключами или разрешением ограничения REPLACE, не учитываются.

Изменения в представлении, перехваченные триггерами INSTEAD OF, не учитываются. Значение, возвращаемое sqlite3_changes() сразу после выполнения операторов INSERT, UPDATE или DELETE в представлении, всегда равно нулю. Учитываются только изменения, внесённые в реальные таблицы.

Дело обстоит сложнее, если функция sqlite3_changes() выполняется во время работы программы триггера. Это может произойти, если программа использует SQL-функцию changes() или если какая-либо другая функция обратного вызова вызывает sqlite3_changes() напрямую. В сущности:

• Перед входом в программу триггера значение, возвращаемое функцией sqlite3_changes(), сохраняется. После завершения работы программы триггера исходное значение восстанавливается.

• Внутри программы триггера каждый оператор INSERT, UPDATE и DELETE устанавливает значение, возвращаемое sqlite3_changes(), по завершении как обычно. Конечно, это значение не будет включать изменения, выполненные подтриггерами, поскольку значение sqlite3_changes() будет сохранено и восстановлено после выполнения каждого подтриггера.

Это означает, что если функция SQL changes() (или аналогичная) используется первым оператором INSERT, UPDATE или DELETE в триггере, то она возвращает значение, установленное при начале выполнения вызывающего оператора. Если она используется вторым или последующим таким оператором в программе триггера, то возвращаемое значение отражает количество строк, изменённых предыдущим оператором INSERT, UPDATE или DELETE в том же триггере.

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

См. также:

• Интерфейс sqlite3_total_changes()
• Предикат count_changes
• SQL-функция changes()
• Предикат data_version

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

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_backup, он возвращает SQLITE_OK независимо, но вместо немедленного освобождения соединения с базой данных, он помечает соединение с базой данных как неиспользуемое «зомби» и принимает меры для автоматического освобождения соединения с базой данных после завершения всех подготовленных запросов, закрытия всех дескрипторов 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*)
);

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

Если функция зарегистрирована с помощью API 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_stmt не будет уничтожен с помощью sqlite3_finalize() или пока запрос не будет автоматически переподготовлен первым вызовом sqlite3_step() для конкретного выполнения, или пока та же информация не будет запрошена снова с другим кодированием.

Возвращаемые имена — это исходные неалиасованные имена базы данных, таблицы и столбца.

Первый аргумент этих интерфейсов — подготовленный запрос sqlite3_stmt. Эти функции возвращают информацию о 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 нет, то имя столбца не определено и может меняться от одной версии 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. Обратный вызов отката вызывается при откате, который получен в результате возвращения ненулевого значения функцией обратного вызова подтверждения, так же, как и при любом другом откате.

В целях этой API транзакция считается откаченной, если выполняется явное утверждение «ROLLBACK» или ошибка или ограничение вызывает неявный откат. Обратный вызов отката не вызывается, если транзакция автоматически откатывается из-за закрытия соединения с базой данных.

См. также интерфейс sqlite3_update_hook().

Диагностика параметров компиляции библиотеки во время выполнения

#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-функции sqlite_compileoption_used() и sqlite_compileoption_get() и псевдоним compile_options.

Определение, является ли 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() будет ненулевым независимо от того, является ли введенный 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 для eTextRep заставляет строки начинаться с четного адреса байта.

Четвертый аргумент, 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() с аргументом xDestroy, отличным от NULL, должны проверять код возврата и сами удалять указатель на данные приложения, а не полагаться на 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 и файлом WAL W и с 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 равно нулю. Ни один из 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(), могут возникнуть проблемы, такие как повреждение кучи или сегментация. Значение 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) при необходимости освобождения указателя 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) возвращает числовой код результата или расширенный код результата для этого вызова API. Интерфейс 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 соответственно, или NULL, если сообщение об ошибке недоступно. (См. как SQLite обрабатывает неверный UTF для исключений из этого правила.) Память для строки сообщения об ошибке управляется внутри. Приложению не нужно беспокоиться об освобождении результата. Однако строка ошибки может быть перезаписана или удалена последующими вызовами других функций интерфейса SQLite.

Интерфейс sqlite3_errstr(E) возвращает текст на английском языке, описывающий код результата E в формате UTF-8, или NULL, если E не является кодом результата, для которого доступно текстовое сообщение об ошибке. Память для хранения строки сообщения об ошибке управляется внутри и не должна освобождаться приложением.

Если последняя ошибка ссылается на конкретный токен в входном 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 — имя файла базы данных sqlite, файла журнала или файла WAL, переданное ядром SQLite в VFS, то sqlite3_filename_database(F) возвращает имя соответствующего файла базы данных.

Если F — имя файла базы данных sqlite, файла журнала или файла WAL, переданное ядром SQLite в VFS, или если F — имя файла базы данных, полученное из sqlite3_db_filename(), то sqlite3_filename_journal(F) возвращает имя соответствующего файла журнала отката.

Если F — имя файла базы данных sqlite, файла журнала или файла WAL, переданное ядром SQLite в VFS, или если F — имя файла базы данных, полученное из sqlite3_db_filename(), то sqlite3_filename_wal(F) возвращает имя соответствующего файла WAL.

Во всех перечисленных случаях, если F не является именем файла базы данных, журнала или WAL, переданным ядром SQLite в VFS, и 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() не может получить достаточную свободную память, она возвращает нулевой указатель. Если параметр N для sqlite3_malloc() равен нулю или отрицателен, то sqlite3_malloc() возвращает нулевой указатель.

Процедура sqlite3_malloc64(N) работает так же, как sqlite3_malloc(N), за исключением того, что N является беззнаковым 64-битным целым числом вместо знакового 32-битным.

Вызов sqlite3_free() с указателем, ранее возвращенным sqlite3_malloc() или sqlite3_realloc(), освобождает эту память, чтобы она могла быть повторно использована. Процедура sqlite3_free() — это команда без действия, если она вызывается с нулевым указателем. Передача нулевого указателя в sqlite3_free() безвредна. После освобождения память не должна ни читаться, ни записываться. Даже чтение ранее освобожденной памяти может привести к ошибке сегментации или другой серьезной ошибке. Повреждение памяти, ошибка сегментации или другая серьезная ошибка могут возникнуть, если sqlite3_free() вызывается с ненулевым указателем, который не был получен из sqlite3_malloc() или sqlite3_realloc().

Интерфейс sqlite3_realloc(X,N) пытается изменить размер предыдущего выделения памяти X, чтобы он был не менее N байтов. Если параметр X для sqlite3_realloc(X,N) является нулевым указателем, то его поведение идентично вызову sqlite3_malloc(N). Если параметр N для sqlite3_realloc(X,N) равен нулю или отрицателен, то поведение точно такое же, как при вызове 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-битное беззнаковое целое число вместо 32-битного знакового целого числа.

Если X — это выделение памяти, ранее полученное из sqlite3_malloc(), sqlite3_malloc64(), sqlite3_realloc() или sqlite3_realloc64(), то sqlite3_msize(X) возвращает размер этого выделения памяти в байтах. Значение, возвращаемое sqlite3_msize(X), может быть больше, чем количество байтов, запрошенных при выделении X. Если X — нулевой указатель, то sqlite3_msize(X) возвращает ноль. Если 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 указателей указывают на нуль-терминированные строки, содержащие имена столбцов. Остальные записи указывают на результаты запроса. Нулевые значения приводят к нулевым указателям. Все остальные значения представлены в их нуль-терминированном представлении 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 её второго параметра и возвращает таблицу результатов в указатель, заданный в её третьем параметре.

После завершения работы с результатом из sqlite3_get_table(), приложение должно передать указатель на таблицу результатов в sqlite3_free_table(), чтобы освободить память, которая была выделена. Из-за того, как происходит выделение sqlite3_malloc() внутри sqlite3_get_table(), вызывающая функция не должна пытаться вызвать sqlite3_free() напрямую. Только sqlite3_free_table() может правильно и безопасно освободить память.

Интерфейс 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 равно нулю для левого аргумента функции. Если нет дополнительных данных, связанных с аргументом функции, интерфейс sqlite3_get_auxdata(C,N) возвращает нулевой указатель.

Интерфейс 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() при возникновении ошибки выделения памяти.
• во время исходного вызова sqlite3_set_auxdata() если функция вычисляется во время планирования запроса вместо выполнения запроса, как иногда происходит с SQLITE_ENABLE_STAT4.

Обратите особое внимание на последние два пункта. Деструктор X в sqlite3_set_auxdata(C,N,P,X) может быть вызван немедленно, до того, как интерфейс sqlite3_set_auxdata() даже вернет значение. Следовательно, sqlite3_set_auxdata() следует вызывать в конце реализации функции, и реализация функции не должна использовать P после того, как был вызван sqlite3_set_auxdata(). Кроме того, вызов sqlite3_get_auxdata(), который происходит сразу после соответствующего вызова sqlite3_set_auxdata(), может всё ещё вернуть NULL, если произошла ошибка недостатка памяти во время вызова 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 или нулевой указатель, если не было предыдущих вызовов sqlite3_set_clientdata() с теми же значениями D и N. Имена сравниваются с помощью strcmp() и, следовательно, чувствительны к регистру.

Если P и X оба не равны NULL, то деструктор X вызывается с аргументом P в первом из следующих случаев:

• Во время вызова sqlite3_set_clientdata(), который пытается зарегистрировать указатель P, возникает ошибка недостатка памяти.
• Делается последующий вызов sqlite3_set_clientdata(D,N,P,X) с теми же параметрами D и N.
• Соединение с базой данных закрывается. SQLite не гарантирует порядок вызова деструкторов, только то, что все деструкторы будут вызваны ровно один раз в какой-то момент процесса закрытия соединения с базой данных.

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

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

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

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

Данные клиента соединения с базой данных доступны только для версии SQLite 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() не может инициализировать библиотеку (например, не может выделить необходимый ресурс, такой как мьютекс), она возвращает код ошибки, отличный от 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*);

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

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

Если операция SQL почти завершена в момент вызова sqlite3_interrupt(), у неё может не быть возможности прерваться и она может быть завершена до конца.

Прерванная операция SQL вернёт SQLITE_INTERRUPT. Если прерванная операция SQL — INSERT, UPDATE или DELETE внутри явного транзакции, то вся транзакция будет автоматически откат.

Вызов sqlite3_interrupt(D) действует до тех пор, пока все текущие выполняемые операторы SQL для соединения с базой данных D не завершатся. Любые новые операторы SQL, начатые после вызова sqlite3_interrupt() и до достижения нулевого значения счётчика запущенных операций, прерываются так, как если бы они выполнялись до вызова sqlite3_interrupt(). Новые операторы SQL, начатые после достижения нулевого значения счётчика запущенных операций, не затрагиваются вызовом sqlite3_interrupt(D). Вызов sqlite3_interrupt(D), произведённый, когда нет выполняемых операторов SQL, является операцией без эффекта и не влияет на операторы SQL, начатые после возвращения sqlite3_interrupt().

Интерфейс 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() возвращает целое число, равное SQLITE_VERSION_NUMBER. Функция sqlite3_sourceid() возвращает указатель на строковую константу, значение которой совпадает с препроцессорным макросом SQLITE_SOURCE_ID C. За исключением случаев, когда 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_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). Подробную информацию см. в документации встроенной функции printf().

Процедуры 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() — это версия с переменным числом аргументов функции sqlite3_snprintf().

См. также: встроенная функция printf(), функция printf() SQL

Мьютексы

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 содержит несколько реализаций этих процедур мьютекса. Соответствующая реализация выбирается автоматически во время компиляции. Следующие реализации доступны в ядре 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"), то никакая реализация мьютекса не включается в библиотеку. В этом случае приложение должно предоставить собственную реализацию мьютекса, используя опцию SQLITE_CONFIG_MUTEX функции sqlite3_config(), перед вызовом sqlite3_initialize() или любой другой публичной функции sqlite3_, которая вызывает sqlite3_initialize().

Процедура sqlite3_mutex_alloc() выделяет новый мьютекс и возвращает указатель на него. Процедура sqlite3_mutex_alloc() возвращает NULL, если не удаётся выделить запрашиваемый мьютекс. Аргумент процедуры 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() создать новый мьютекс. Новый мьютекс является рекурсивным, когда используется SQLITE_MUTEX_RECURSIVE, но необязательно, когда используется SQLITE_MUTEX_FAST. Реализация мьютекса не должна различать SQLITE_MUTEX_RECURSIVE и SQLITE_MUTEX_FAST, если она этого не хочет. SQLite будет запрашивать только рекурсивный мьютекс в тех случаях, когда он действительно нужен. Если на целевой платформе доступна более быстрая нерекурсивная реализация мьютекса, подсистема мьютекса может вернуть такой мьютекс в ответ на SQLITE_MUTEX_FAST.

Другие разрешённые параметры для sqlite3_mutex_alloc() (кроме SQLITE_MUTEX_FAST и SQLITE_MUTEX_RECURSIVE) каждый возвращают указатель на статический предварительно существующий мьютекс. Текущая версия SQLite использует девять статических мьютексов. Будущие версии SQLite могут добавить дополнительные статические мьютексы. Статические мьютексы предназначены только для внутреннего использования SQLite. Приложения, использующие мьютексы SQLite, должны использовать только динамические мьютексы, возвращаемые SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE.

Обратите внимание, что если используется один из динамических параметров мьютекса (SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE), то sqlite3_mutex_alloc() возвращает другой мьютекс при каждом вызове. Для статических типов мьютексов возвращается тот же мьютекс при каждом вызове с одинаковым номером типа.

Процедура sqlite3_mutex_free() освобождает ранее выделенный динамический мьютекс. Попытка освободить статический мьютекс приводит к неопределённому поведению.

Процедуры sqlite3_mutex_enter() и sqlite3_mutex_try() пытаются войти в мьютекс. Если другой поток уже находится в мьютексе, sqlite3_mutex_enter() заблокируется, а sqlite3_mutex_try() вернёт SQLITE_BUSY. Интерфейс sqlite3_mutex_try() возвращает SQLITE_OK при успешном входе. Мьютексы, созданные с помощью SQLITE_MUTEX_RECURSIVE, могут быть введены в поток несколько раз одним и тем же потоком. В таких случаях мьютекс должен быть покинут равное количество раз, прежде чем другой поток сможет войти. Если один и тот же поток пытается войти в любой мьютекс, отличный от SQLITE_MUTEX_RECURSIVE, более одного раза, поведение неопределённо.

Некоторые системы (например, Windows 95) не поддерживают операцию, реализованную sqlite3_mutex_try(). На этих системах sqlite3_mutex_try() всегда возвращает SQLITE_BUSY. В большинстве случаев ядро SQLite использует sqlite3_mutex_try() только в качестве оптимизации, поэтому это приемлемое поведение. Исключение составляют сборки Unix, которые устанавливают параметр компиляции SQLITE_ENABLE_SETLK_TIMEOUT. В этом случае требуется работающая sqlite3_mutex_try().

Процедура sqlite3_mutex_leave() выходит из мьютекса, который ранее был введён тем же потоком. Поведение неопределённо, если мьютекс не введён вызывающим потоком или не выделен.

Если аргумент функций sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave() или sqlite3_mutex_free() является NULL-указателем, то любая из четырёх процедур ведёт себя как команда бездействия.

См. также: sqlite3_mutex_held() и sqlite3_mutex_notheld().

Процедуры проверки мьютекса

#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. Внешние реализации мьютексов обязаны предоставить эти процедуры, только если определён SQLITE_DEBUG и не определён NDEBUG.

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

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

Если аргументом для sqlite3_mutex_held() является указатель NULL, то процедура должна возвращать 1. Это кажется нелогичным, поскольку очевидно, что мьютекс не может быть удержан, если он не существует. Но причина, по которой мьютекс не существует, заключается в том, что сборка не использует мьютексы. И мы не хотим, чтобы утверждение, содержащее вызов 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, как указано в аргументе filename. Аргумент filename интерпретируется как UTF-8 для sqlite3_open() и sqlite3_open_v2() и как UTF-16 в родном порядке байтов для sqlite3_open16(). Диспетчер подключения к базе данных обычно возвращается в *ppDb, даже если произошла ошибка. Исключением является ситуация, когда SQLite не может выделить память для хранения объекта sqlite3, в *ppDb записывается NULL вместо указателя на объект 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(), за исключением того, что он принимает два дополнительных параметра для дополнительного управления новым подключением к базе данных. Параметр flags для sqlite3_open_v2() должен по крайней мере включать одну из следующих трёх комбинаций флагов:

SQLITE_OPEN_READONLY

База данных открывается в режиме только для чтения. Если база данных ещё не существует, возвращается ошибка.

SQLITE_OPEN_READWRITE

База данных открывается для чтения и записи, если это возможно, или только для чтения, если файл защищён от записи операционной системой. В любом случае база данных должна уже существовать, в противном случае возвращается ошибка. По историческим причинам, если открытие в режиме чтения и записи терпит неудачу из-за разрешений на уровне ОС, выполняется попытка открыть её в режиме только для чтения. 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

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

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_*, то поведение не определено. Исторические версии SQLite молча игнорировали избыточные биты в параметре flags для 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 по умолчанию.

Если filename равно ":memory:", то для подключения создается частная временная база данных в памяти. Эта база данных в памяти исчезнет при закрытии подключения к базе данных. Будущие версии SQLite могут использовать дополнительные специальные имена файлов, начинающиеся с символа ":". Рекомендуется, чтобы при имени файла базы данных, фактически начинающемся с символа ":", вы предваряли имя файла путем, например, "./", чтобы избежать неоднозначности.

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

Имена файлов URI

Если интерпретация имени файла URI включена, и аргумент filename начинается с "file:", то имя файла интерпретируется как URI. Интерпретация имени файла URI включена, если флаг SQLITE_OPEN_URI установлен в третьем аргументе sqlite3_open_v2(), или если она была включена глобально с помощью параметра SQLITE_CONFIG_URI метода sqlite3_config() или параметром SQLITE_USE_URI на этапе компиляции. Интерпретация имени файла URI выключена по умолчанию, но будущие релизы SQLite могут включить интерпретацию имени файла URI по умолчанию. Дополнительная информация см. в разделе "Имена файлов URI".

Имена файлов URI анализируются в соответствии с RFC 3986. Если URI содержит авторитет, он должен быть либо пустой строкой, либо строкой "localhost". Если авторитет не является пустой строкой или "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: Параметр mode может быть установлен в "ro", "rw", "rwc" или "memory". Попытка установить его в любое другое значение является ошибкой. Если указано "ro", то база данных открывается для чтения только для чтения, так же как если бы флаг SQLITE_OPEN_READONLY был установлен в третьем аргументе sqlite3_open_v2(). Если параметр mode установлен в "rw", то база данных открывается для чтения и записи (но не для создания), как если бы был установлен SQLITE_OPEN_READWRITE (но не SQLITE_OPEN_CREATE). Значение "rwc" эквивалентно установке как SQLITE_OPEN_READWRITE, так и SQLITE_OPEN_CREATE. Если параметр mode установлен в "memory", то используется чистая база данных в памяти, которая никогда не читает и не записывает данные с диска. Указание значения параметра mode, которое менее ограничительно, чем указано флагами, переданными в третьем параметре sqlite3_open_v2(), является ошибкой.

• cache: Параметр cache может быть установлен в "shared" или "private". Установка его в "shared" эквивалентна установке бита SQLITE_OPEN_SHAREDCACHE в аргументе flags, переданном в sqlite3_open_v2(). Установка параметра cache в "private" эквивалентна установке бита SQLITE_OPEN_PRIVATECACHE. Если используется sqlite3_open_v2(), и параметр "cache" присутствует в имени файла URI, его значение переопределяет любое поведение, запрошенное установкой флага SQLITE_OPEN_PRIVATECACHE или SQLITE_OPEN_SHAREDCACHE.

• psow: Параметр psow указывает, применяется ли свойство powersafe overwrite к носителю данных, на котором находится файл базы данных.

• nolock: Параметр nolock — это булевый параметр запроса, который, если установлен, отключает блокировку файлов в режимах журнала отката. Это полезно для доступа к базе данных на файловой системе, которая не поддерживает блокировку. Осторожно: повреждение базы данных может произойти, если два или более процессов записывают в одну и ту же базу данных, и любой из этих процессов использует nolock=1.

• immutable: Параметр immutable — это булевый параметр запроса, который указывает, что файл базы данных хранится на носителе только для чтения. При установке immutable SQLite предполагает, что файл базы данных не может быть изменен, даже процессом с более высокими привилегиями, и поэтому база данных открывается для чтения только для чтения, а все блокировки и обнаружение изменений отключаются. Осторожно: установка свойства immutable для файла базы данных, который на самом деле изменяется, может привести к некорректным результатам запросов и/или ошибкам SQLITE_CORRUPT. См. также: SQLITE_IOCAP_IMMUTABLE.

Указание неизвестного параметра в компоненте запроса URI не является ошибкой. Будущие версии SQLite могут понимать дополнительные параметры запроса. Дополнительную информацию см. в "параметрах запроса со специальным значением для 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", который использует файлы с точкой вместо позиционных консультационных блокировок.
file:data.db?mode=readonly	Ошибка. "readonly" — не допустимое значение для параметра "mode". Используйте "ro" вместо него: "file:data.db?mode=ro".

В компонентах пути и запроса URI поддерживаются шестнадцатеричные последовательности с экранированием (%HH). Шестнадцатеричная последовательность с экранированием состоит из знака процента - "%" - за которым следуют ровно две шестнадцатеричные цифры, определяющие значение октета. Перед интерпретацией компонентов пути или запроса имени файла URI они кодируются с помощью UTF-8, и все шестнадцатеричные последовательности с экранированием заменяются одним байтом, содержащим соответствующий октет. Если этот процесс генерирует недопустимое кодирование 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() регистрирует функцию обратного вызова, которая вызывается перед каждой операцией ВСТАВКИ, ОБНОВЛЕНИЯ и УДАЛЕНИЯ в таблице базы данных. Одновременно на одном соединении с базой данных может быть зарегистрирован не более одного обработчика пред-обновления; каждый вызов sqlite3_preupdate_hook() переопределяет предыдущее значение. Обработчик пред-обновления отключается путем вызова sqlite3_preupdate_hook() со значением NULL в качестве второго параметра. Третий параметр sqlite3_preupdate_hook() передается как первый параметр функциям обратного вызова.

Обработчик пред-обновления срабатывает только для изменений в реальных таблицах базы данных; обработчик пред-обновления не вызывается для изменений в виртуальных таблицах или в системных таблицах, таких как sqlite_sequence или sqlite_stat1.

Второй параметр функции обратного вызова пред-обновления — указатель на соединение с базой данных, которое зарегистрировало обработчик пред-обновления. Третий параметр функции обратного вызова пред-обновления — одна из констант SQLITE_INSERT, SQLITE_DELETE или SQLITE_UPDATE, которая определяет вид операции обновления, которая должна произойти. Четвертый параметр функции обратного вызова пред-обновления — имя базы данных в рамках соединения с базой данных, которая изменяется. Будет "main" для основной базы данных или "temp" для временных таблиц или имя, указанное после ключевого слова AS в операторе ATTACH для подключенных баз данных. Пятый параметр функции обратного вызова пред-обновления — имя таблицы, которая изменяется.

Для операции UPDATE или DELETE в таблице с идентификаторами строк шестой параметр, переданный функции обратного вызова пред-обновления, — начальный идентификатор строки строки, которая изменяется или удаляется. Для операции INSERT в таблице с идентификаторами строк или любой операции в таблице БЕЗ идентификаторов строк значение шестого параметра не определено. Для операции INSERT или UPDATE в таблице с идентификаторами строк седьмой параметр — конечное значение идентификатора строки вставленной или обновлённой строки. Значение седьмого параметра, переданного функции обратного вызова, не определено для операций в таблицах БЕЗ идентификаторов строк или для операций DELETE в таблицах с идентификаторами строк.

Функция 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 указатель на защищённый sqlite3_value, который содержит значение N-го столбца строки таблицы до её обновления. Параметр N должен быть в диапазоне от 0 до значения, на единицу меньшего, чем количество столбцов, иначе поведение будет неопределённым. Это должно использоваться только в функциях обратного вызова пред-обновления SQLITE_UPDATE и SQLITE_DELETE; если оно используется функцией обратного вызова SQLITE_INSERT, поведение будет неопределённым. sqlite3_value, на который указывает P, будет уничтожен при возвращении функции обратного вызова пред-обновления.

Интерфейс sqlite3_preupdate_new(D,N,P) записывает в P указатель на защищённый sqlite3_value, который содержит значение N-го столбца строки таблицы после её обновления. Параметр N должен быть в диапазоне от 0 до значения, на единицу меньшего, чем количество столбцов, иначе поведение будет неопределённым. Это должно использоваться только в функциях обратного вызова пред-обновления SQLITE_INSERT и SQLITE_UPDATE; если оно используется функцией обратного вызова SQLITE_DELETE, поведение будет неопределённым. sqlite3_value, на который указывает P, будет уничтожен при возвращении функции обратного вызова пред-обновления.

Интерфейс sqlite3_preupdate_depth(D) возвращает 0, если функция обратного вызова пред-обновления была вызвана в результате прямой операции вставки, обновления или удаления; или 1 для операций вставки, обновления или удаления, вызванных триггерами верхнего уровня; или 2 для изменений, результат которых — вызовы триггеров, вызванные триггерами верхнего уровня; и так далее.

При использовании API sqlite3_blob_write() для обновления столбца BLOB, вызывается предварительный обработчик с кодом SQLITE_DELETE. Это происходит потому, что в этом случае новые значения недоступны. В этом случае, когда обратный вызов, сделанный с op==SQLITE_DELETE, фактически является записью с помощью API sqlite3_blob_write(), функция sqlite3_preupdate_blobwrite() возвращает индекс записываемого столбца. В других случаях, когда предварительный обработчик вызывается по какой-либо другой причине, включая обычное удаление, 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*);

Эти функции устарели. Используйте интерфейс sqlite3_trace_v2() вместо функций, описанных здесь.

Эти функции регистрируют функции обратного вызова, которые могут использоваться для отслеживания и профилирования выполнения 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_bind_blob, используемых для привязки значений к параметрам хоста в подготовленных запросах. Дополнительную информацию см. в документации по SQL параметрам.

Интерфейс sqlite3_result_blob() устанавливает результат от пользовательской функции как BLOB, содержимое которого указывается вторым параметром и длина которого составляет N байт, где N — третий параметр.

Интерфейсы sqlite3_result_zeroblob(C,N) и sqlite3_result_zeroblob64(C,N) устанавливают результат пользовательской функции как BLOB, содержащий все нулевые байты и имеющий размер N байт.

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

Функции sqlite3_result_error() и sqlite3_result_error16() вызывают исключение для реализованной SQL-функции. SQLite использует строку, указанную вторым параметром функций 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 использует указанное количество байт (а не символов) из второго параметра как сообщение об ошибке. Функции 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-битное целое со знаком, указанное во втором аргументе. Интерфейс sqlite3_result_int64() устанавливает возвращаемое значение пользовательской функции как 64-битное целое со знаком, указанное во втором аргументе.

Интерфейс 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*. Если третий параметр любого из интерфейсов sqlite3_result_text*, кроме sqlite3_result_text64(), отрицательный, то SQLite вычисляет длину строки, найдя в втором параметре первый нулевой символ. Если третий параметр интерфейсов sqlite3_result_text* неотрицателен, то в качестве результата пользовательской функции используется указанное количество байт (а не символов) текста, указанного вторым параметром. Если третий параметр неотрицателен, то он должен представлять байтовый смещение в строке, где бы появился нулевой терминатор, если бы строка была завершена нулевым символом. Если в строке встречаются нулевые символы в байтовом смещении, меньшем значения третьего параметра, то результирующая строка будет содержать встроенные нули, а результат операций над строками со встроенными нулями не определён. Если четвёртый параметр интерфейсов sqlite3_result_text* или sqlite3_result_blob является не нулевым указателем, то SQLite вызывает эту функцию в качестве деструктора для текстового или BLOB результата, когда закончит использовать этот результат. Если четвёртый параметр интерфейсов sqlite3_result_text* или sqlite3_result_blob — специальная константа SQLITE_STATIC, то SQLite предполагает, что текстовый или BLOB результат находится в постоянном пространстве и не копирует содержимое параметра, а также не вызывает деструктор для содержимого, когда закончит использовать этот результат. Если четвёртый параметр интерфейсов 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, неверные символы могут быть преобразованы в заменяющий символ Юникода U+FFFD.

Интерфейс sqlite3_result_value() устанавливает результат пользовательской функции как копию объекта sqlite3_value, указанного вторым параметром. Интерфейс 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() является частью интерфейса передачи указателей pointer passing interface, добавленного для 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() с параметром flags, установленным в ноль.

Параметр «idx» определяет конкретный элемент запроса, для которого нужно получить статистику. Элементы запроса нумеруются, начиная с нуля. Значение -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, до нулевой длины.

Эти методы не возвращают код результата. При возникновении ошибки этот факт записывается в объект 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_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);

API sqlite3_stricmp() и sqlite3_strnicmp() позволяют приложениям и расширениям сравнивать содержимое двух буферов, содержащих строки UTF-8, не учитывая регистр, используя то же определение "не учета регистра", что и 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.

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

См. также:

• интерфейс sqlite3_changes()
• псевдоним count_changes
• SQL-функция changes()
• псевдоним data_version
• файловый контроль SQLITE_FCNTL_DATA_VERSION

Получение значений параметров 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" в любом регистре, или если значение начинается с нуля. Если 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 версии 3.31.0 (2020-01-22), параметр F ввода может также представлять имя файла журнала отката или файла WAL, помимо основного файла базы данных. До версии 3.31.0 эти функции работали только в том случае, если F был именем основного файла базы данных. Когда параметр F является именем файла журнала отката или файла WAL, он имеет доступ ко всем тем же параметрам запроса, которые были найдены в основном файле базы данных.

Дополнительную информацию см. в документации по файловому имени URI.

Получение значений 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 value 


sqlite3_value_double
→
REAL value 


sqlite3_value_int
→
32-bit INTEGER value 


sqlite3_value_int64
→
64-bit INTEGER value 


sqlite3_value_pointer
→
Pointer value 


sqlite3_value_text
→
UTF-8 TEXT value 


sqlite3_value_text16
→
UTF-16 TEXT value in the native byteorder 


sqlite3_value_text16be
→
UTF-16be TEXT value 


sqlite3_value_text16le
→
UTF-16le TEXT value 


 
 
 


sqlite3_value_bytes
→
Size of a BLOB or a UTF-8 TEXT in bytes 



sqlite3_value_bytes16  
→ 
Size of UTF-16 TEXT in bytes 


sqlite3_value_type
→
Default datatype of the value 



sqlite3_value_numeric_type  
→ 
Best numeric datatype of the value 



sqlite3_value_nochange  
→ 
True if the column is unchanged in an UPDATE against a virtual table. 



sqlite3_value_frombind  
→ 
True if value originated from a bound parameter 

Подробное описание:

Эти функции извлекают информацию о типе, размере и содержимом из объектов protected sqlite3_value. Объекты 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 соответственно в формате big-endian и little-endian.

Если объект 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() пытается применить числовую аффинити к значению. Это означает, что выполняется попытка преобразовать значение в целое число или число с плавающей точкой. Если такое преобразование возможно без потери информации (иначе говоря, если значение является строкой, которая выглядит как число), то преобразование выполняется. В противном случае преобразование не выполняется. Тип данных после преобразования возвращается.

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

Интерфейс sqlite3_value_frombind(X) возвращает ненулевое значение, если значение X происходит от одного из интерфейсов sqlite3_bind(). Если X происходит из SQL-литерального значения, значения столбца таблицы или выражения, то sqlite3_value_frombind(X) возвращает ноль.

Обратите особое внимание на то, что указатель, возвращаемый 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 стандартной, ее нужно снова зарегистрировать с установленным флагом 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 в указатель на первое или следующее значение в правой части ограничения IN. Если больше нет значений в правой части ограничения IN, то *P устанавливается в NULL, и эти функции возвращают SQLITE_DONE. Возвращаемое значение может быть каким-либо другим значением, например, SQLITE_NOMEM, в случае сбоя.

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

Интерфейс, специфичный для 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; ненулевое значение будет скопировано в память, полученную из 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 используется более одного раза, второй и последующие случаи имеют тот же индекс, что и первый случай. Индекс для именованных параметров можно найти, используя API sqlite3_bind_parameter_index(), если это необходимо. Индекс для параметров "?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, то он должен быть указателем на правильно сформированную строку Юникода, которая является либо UTF8, если шестой параметр равен SQLITE_UTF8, или UTF16 в противном случае.

Порядок байтов текста UTF16 определяется знаком порядка байтов (BOM, U+FEFF), найденным в первом символе, который удаляется, или в отсутствие BOM порядок байтов — это родной порядок байтов машины-хозяина для sqlite3_bind_text16() или порядок байтов, указанный в шестом параметре для sqlite3_bind_text64(). Если текст UTF16 содержит недопустимые символы Юникода, то SQLite может изменить эти недопустимые символы на символ замены Юникода: U+FFFD.

В тех процедурах, которые имеют четвертый аргумент, его значение — это количество байтов в параметре. Чтобы быть ясными: значение — это количество байтов в значении, а не количество символов. Если четвертый параметр для sqlite3_bind_text() или sqlite3_bind_text16() отрицательный, то длина строки — это количество байтов до первого нулевого терминатора. Если четвертый параметр для sqlite3_bind_blob() отрицательный, то поведение не определено. Если указан ненулевой четвертый параметр для sqlite3_bind_text() или sqlite3_bind_text16() или sqlite3_bind_text64(), то этот параметр должен быть смещением байта, где произошел бы нулевой терминатор, предполагая, что строка завершается нулем. Если какие-либо нулевые символы встречаются в смещениях байтов меньше значения четвертого параметра, то результирующее значение строки будет содержать вставленные нули. Результат выражений, включающих строки с вставленными нулями, не определён.

Пятый аргумент интерфейсов привязки BLOB и строк управляет или указывает продолжительность жизни объекта, на который ссылается третий параметр. Существуют три варианта: (1) Может быть передан деструктор для удаления BLOB или строки после того, как SQLite закончит с ним. Он вызывается для удаления 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 использует фиксированный объём памяти (только целое число для хранения его размера) во время обработки. Zeroblobs предназначены для того, чтобы служить заполнителями для BLOB, содержимое которых впоследствии записывается с использованием функций инкрементного ввода-вывода BLOB. Отрицательное значение для 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 для подготовленного оператора или с подготовленным оператором, для которого 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 положительный, zSql читается до первого нулевого терминатора или до тех пор, пока не будет считано nByte байтов, в зависимости от того, что произойдет раньше. Если nByte равен нулю, то подготовленный оператор не создается. Если вызывающий код знает, что предоставленная строка имеет нулевой терминатор, то есть небольшое преимущество производительности при передаче параметра nByte, являющегося количеством байтов в строке ввода включая нулевой терминатор. Обратите внимание, что nByte измеряет длину входных данных в байтах, а не символах, даже для интерфейсов UTF-16.

Если 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-утверждение и попытается выполнить его снова. Прежде чем sqlite3_step() откажется и вернёт ошибку, будет выполнено не более SQLITE_MAX_SCHEMA_RETRY попыток.
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(). Второй параметр обратного вызова — целочисленный код действия, определяющий конкретное действие, которое нужно авторизовать. Третий-шестой параметры обратного вызова — либо указатели NULL, либо завершающиеся нулём строки, содержащие дополнительные сведения о действии, которое нужно авторизовать. Приложения должны быть всегда готовы к встрече с указателем NULL в любом из параметров с третьего по шестой в обратном вызове авторизации.

Если код действия — SQLITE_READ, а обратный вызов возвращает SQLITE_IGNORE, то подготовленное утверждение sqlite3_stmt строится таким образом, чтобы заменить значение NULL в столбце таблицы, который был бы прочитан, если бы был возвращён SQLITE_OK. Возвращаемое значение SQLITE_IGNORE может быть использовано для запрета доступа ненадёжному пользователю к отдельным столбцам таблицы. Когда таблица упоминается в SELECT, но значения столбцов из этой таблицы не извлекаются (например, в запросе «SELECT count(*) FROM tab»), тогда обработчик авторизации SQLITE_READ вызывается один раз для этой таблицы со значением столбца, которое является пустой строкой. Если код действия — SQLITE_DELETE, а обратный вызов возвращает SQLITE_IGNORE, то операция DELETE выполняется, но оптимизация усечения truncate optimization отключена, и все строки удаляются по отдельности.

Обработчик авторизации используется при подготовке SQL-утверждений из ненадежного источника, чтобы гарантировать, что 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() для переподготовки утверждения после изменения схемы.

Проверка режима авто-записи

int sqlite3_get_autocommit(sqlite3*);

Интерфейс sqlite3_get_autocommit() возвращает ненулевое значение или ноль, если данное соединение с базой данных находится или не находится в режиме автозаписи соответственно. Режим автозаписи включен по умолчанию. Режим автозаписи отключается оператором BEGIN. Режим автозаписи включается операторами COMMIT или ROLLBACK.

Если при выполнении утверждения в транзакции с несколькими утверждениями возникают определённые типы ошибок (включая SQLITE_FULL, SQLITE_IOERR, SQLITE_NOMEM, SQLITE_BUSY и SQLITE_INTERRUPT), транзакция может быть автоматически отменена. Единственный способ узнать, автоматически ли SQLite отменила транзакцию после возникновения ошибки — использовать эту функцию.

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

Регистрация обработчика для обработки ошибок 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 result 


sqlite3_column_double
→
REAL result 


sqlite3_column_int
→
32-bit INTEGER result 


sqlite3_column_int64
→
64-bit INTEGER result 


sqlite3_column_text
→
UTF-8 TEXT result 


sqlite3_column_text16
→
UTF-16 TEXT result 


sqlite3_column_value
→
The result as an unprotected sqlite3_value object. 


 
 
 


sqlite3_column_bytes
→
Size of a BLOB or a UTF-8 TEXT result in bytes 



sqlite3_column_bytes16  
→ 
Size of UTF-16 TEXT in bytes 


sqlite3_column_type
→
Default datatype of the result 

Подробное описание:

Эти функции возвращают информацию об одном столбце текущей строки результата запроса. В каждом случае первый аргумент — указатель на предварительно подготовленное выражение, которое оценивается (указатель 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() возвращает ноль.

Если результат — 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() возвращает ноль.

Значения, возвращаемые 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(), является неохраняемым объектом sqlite3_value. В многопоточной среде неохраняемый объект sqlite3_value может использоваться безопасно только с sqlite3_bind_value() и sqlite3_result_value(). Если неохраняемый объект 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	TEXT	ASCII-представление целого числа
INTEGER	BLOB	То же, что INTEGER->TEXT
FLOAT	INTEGER	ПРИВЕДЕНИЕ к INTEGER
FLOAT	TEXT	ASCII-представление числа с плавающей точкой
FLOAT	BLOB	ПРИВЕДЕНИЕ к BLOB
TEXT	INTEGER	ПРИВЕДЕНИЕ к INTEGER
TEXT	FLOAT	ПРИВЕДЕНИЕ к REAL
TEXT	BLOB	Без изменений
BLOB	INTEGER	ПРИВЕДЕНИЕ к INTEGER
BLOB	FLOAT	ПРИВЕДЕНИЕ к REAL
BLOB	TEXT	ПРИВЕДЕНИЕ к 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" для временной базы данных, или имя, появляющееся после ключевого слова AS для баз данных, добавленных с помощью SQL-команды ATTACH. Вместо "main" можно использовать указатель NULL для ссылки на основной файл базы данных. Третий и четвёртый параметры этой функции передаются непосредственно второму и третьему параметрам метода xFileControl. Возвращаемое значение метода xFileControl становится возвращаемым значением этой функции.

Некоторые операторы для sqlite3_file_control() обрабатываются ядром SQLite напрямую и никогда не вызывают метод sqlite3_io_methods.xFileControl. Значение SQLITE_FCNTL_FILE_POINTER для параметра op приводит к тому, что указатель на базовый объект sqlite3_file записывается в область памяти, на которую указывает четвёртый параметр. 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 выберет ту, которая включает наименьшее количество преобразования данных.

Четвертый параметр может дополнительно быть объединён с флагом SQLITE_DETERMINISTIC, чтобы указать, что функция всегда будет возвращать один и тот же результат при одинаковых входах в рамках одного SQL-запроса. Большинство SQL-функций детерминированы. Встроенная SQL-функция random() является примером функции, которая не детерминирована. Планировщик запросов SQLite может выполнять дополнительные оптимизации для детерминированных функций, поэтому использование флага SQLITE_DETERMINISTIC рекомендуется по возможности.

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

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

Пятый параметр — произвольный указатель. Реализация функции может получить доступ к этому указателю с помощью sqlite3_user_data().

Шестой, седьмой и восьмой параметры, передаваемые трем функциям «sqlite3_create_function*», 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. Однако такие вызовы не должны закрывать соединение с базой данных, ни завершать, ни сбрасывать подготовленный запрос, в котором выполняется функция.