Спецификация интерфейса 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 */

В качестве аргумента F для sqlite3_serialize(D,S,P,F) можно объединить с помощью побитового ИЛИ одну или несколько следующих констант.

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

Флаги для sqlite3_setlk_timeout()

#define SQLITE_SETLK_BLOCK_ON_CONNECT 0x01

Максимальный индекс xShmLock

#define SQLITE_SHM_NLOCK        8

Метод xShmLock в sqlite3_io_methods может использовать значения от 0 до этой верхней границы в качестве аргумента «offset». Ядро 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, и после этого остаётся неизменной.

Прагма data_store_directory может изменить эту переменную и заставить её указывать на память, выделенную с помощью sqlite3_malloc. Кроме того, прагма data_store_directory всегда предполагает, что любая строка, на которую указывает эта переменная, хранится в памяти, выделенной с помощью sqlite3_malloc, и прагма может попытаться освободить эту память с помощью sqlite3_free. Поэтому, если эта переменная изменяется напрямую, её следует либо установить в NULL, либо заставить указывать на память, выделенную с помощью sqlite3_malloc; в противном случае следует избегать использования прагмы 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 вида:

column OP expr

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

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

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

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

Метод xBestIndex должен заполнить aConstraintUsage[] сведениями о том, какие параметры передавать в xFilter. Если argvIndex>0, то вычисляется правая часть соответствующего элемента aConstraint[], которая становится элементом argv с индексом argvIndex. Если 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 ненулевой указатель, метод sqlite3_io_methods.xClose может быть вызван, даже если sqlite3_vfs.xOpen сообщил о неудаче. Единственный способ предотвратить вызов xClose после неудачного вызова sqlite3_vfs.xOpen — присвоить элементу sqlite3_file.pMethods значение NULL в методе sqlite3_vfs.xOpen.

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

Целочисленные значения для 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_SUBPAGE_READ

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

Если xRead() возвращает SQLITE_IOERR_SHORT_READ, он также должен заполнить нулями непрочитанные области буфера. Может показаться, что VFS, не заполняющая нулями данные при коротком чтении, работает нормально. Однако отсутствие заполнения нулями при коротком чтении в конечном счёте приведёт к повреждению базы данных.

Процедуры выделения памяти

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

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

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

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

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

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

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

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

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

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

Поле 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 устанавливается для временных баз данных и их журналов, временных баз данных и подчинённых журналов.

Флаг 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 предполагает, что после возврата из xOpen элемент sqlite3_file.pMethods будет действительным независимо от успешного или неудачного результата вызова xOpen.

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

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

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

Интерфейсы xSetSystemCall(), xGetSystemCall() и xNextSystemCall() не используются ядром 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 */
};

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

Методы виртуальной таблицы могут задать сообщение об ошибке, присвоив zErrMsg строку, полученную с помощью sqlite3_mprintf(). Перед присвоением zErrMsg новой строки метод должен освободить предыдущую строку вызовом sqlite3_free(). После передачи сообщения об ошибке клиентскому приложению строка будет автоматически освобождена с помощью 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,
     char **pzErrMsg,
     const struct sqlite3_api_routines *pThunk
   );

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

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

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

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

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

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

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

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

int sqlite3_bind_parameter_count(sqlite3_stmt*);

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

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

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

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

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

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

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

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

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

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

Используйте интерфейс sqlite3_blob_bytes(), чтобы определить размер открытого BLOB-объекта. Этот интерфейс не позволяет изменить размер BLOB. Чтобы изменить размер BLOB, используйте команду SQL UPDATE.

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

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

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

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

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

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

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

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

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

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

sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

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

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

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 соответствуют различным присоединенным базам данных ATTACH.

Память для строки, возвращаемой sqlite3_db_name(), управляется самой SQLite. Строка может быть освобождена любой операцией, изменяющей схему, включая ATTACH или DETACH, а также вызовы 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_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 of 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. Если S — нулевой указатель, используется основная база данных. Размер сериализованной базы данных P составляет N байт. M — размер буфера P, который может превышать N. Если M больше N и в F не установлен бит SQLITE_DESERIALIZE_READONLY, SQLite может добавлять данные в базу данных в памяти, пока их общий размер не превысит M байт.

Если в F установлен бит SQLITE_DESERIALIZE_FREEONCLOSE, при закрытии подключения к базе данных 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. Чтобы обойти это ограничение, приложение может перед вызовом sqlite3_deserialize(D,S,P,N,M,F) установить номера версии формата файла (байты 18 и 19) входной базы данных P в значение 0x01, принудительно переведя файл базы данных в режим отката.

Если sqlite3_deserialize(D,S,P,N,M,F) завершится неудачно по любой причине и в аргументе F установлен бит SQLITE_DESERIALIZE_FREEONCLOSE, перед возвратом будет вызвана функция 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 либо указывать на массив указателей на строки, завершающийся единственным нулевым указателем. Если параметр 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-инъекции для получения доступа к возможностям загрузки расширений.

Включить или отключить общий кэш pager

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

Если при выполнении операторов SQL, переданных в sqlite3_exec(), возникает ошибка, выполнение текущего оператора прекращается, а последующие операторы пропускаются. Если пятый параметр sqlite3_exec() не равен NULL, сообщение об ошибке записывается в память, выделенную с помощью sqlite3_malloc(), и возвращается через пятый параметр. Чтобы избежать утечек памяти, после того как строка сообщения об ошибке, возвращенная через пятый параметр sqlite3_exec(), больше не нужна, приложение должно вызвать для нее sqlite3_free(). Если пятый параметр 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() — нулевой указатель, указатель на пустую строку или указатель на строку, содержащую только пробелы и/или комментарии 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() с нулевым указателем безопасен и ничего не делает.

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

Идентификатор последней вставленной строки

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

Некоторые реализации виртуальных таблиц могут вставлять строки в таблицы с 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 последней вставленной строки rowid, значение, возвращаемое sqlite3_last_insert_rowid(), становится непредсказуемым и может не совпадать ни со старым, ни с новым 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-букв или всех буквенно-цифровых символов ASCII в имени файла — от последнего "/" до первой следующей "." — без начального "lib". Интерфейс sqlite3_load_extension() возвращает SQLITE_OK в случае успеха и SQLITE_ERROR в случае ошибки. Если произошла ошибка и pzErrMsg не равен 0, интерфейс sqlite3_load_extension() попытается записать текст сообщения об ошибке в *pzErrMsg, используя память, выделенную с помощью sqlite3_malloc(). Вызывающая функция должна освободить эту память вызовом sqlite3_free().

Перед вызовом этого API необходимо включить загрузку расширений с помощью sqlite3_enable_load_extension() или sqlite3_db_config(db,SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL); в противном случае будет возвращена ошибка.

Предупреждение о безопасности: Рекомендуется использовать метод 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) должен указывать на открытое подключение к базе данных и, в частности, не должен быть нулевым.

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

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

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

Если эта функция ранее не вызывалась либо при предыдущем вызове значение N было меньше единицы или P был нулевым указателем, PRNG инициализируется случайными данными, полученными методом xRandomness объекта sqlite3_vfs по умолчанию. Если при предыдущем вызове этой функции значение N было не меньше 1, а P не был нулевым указателем, псевдослучайные данные генерируются внутри SQLite без обращения к методу 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_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. В текущих версиях SQLite сохраняются только младшие 8 бит подтипа T; старшие биты отбрасываются. В будущих выпусках 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. Если S — указатель NULL, используется главная база данных. Если 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.

Установка кода и сообщения об ошибке

int sqlite3_set_errmsg(sqlite3 *db, int errcode, const char *zErrMsg);

Установить для дескриптора базы данных, переданного в качестве первого аргумента, код ошибки errcode, а в качестве сообщения об ошибке — копию строки zErrMsg, завершающейся нулевым символом. Если в качестве zErrMsg передан NULL, то для сообщения об ошибке устанавливается стандартное сообщение, связанное с указанным кодом ошибки. Последующие вызовы sqlite3_errcode(), sqlite3_errmsg() и подобных функций будут возвращать значения, установленные этой процедурой, вместо ранее установленных самой SQLite.

Эта функция возвращает SQLITE_OK, если код ошибки и сообщение об ошибке успешно установлены, SQLITE_NOMEM при нехватке памяти и SQLITE_MISUSE, если дескриптор базы данных равен NULL или недействителен.

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

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

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

void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);

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

Установка тайм-аута Setlk

int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);

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

Передача этой функции значения 0 полностью отключает блокирующие блокировки. Передача значения -1 запрашивает у VFS длительную блокировку — по возможности бессрочную. Результат передачи любого другого отрицательного значения не определён.

Внутри SQLite каждый дескриптор базы данных хранит два значения тайм-аута: busy-timeout (используется для баз данных в режиме отката или если VFS не поддерживает блокирующие блокировки) и setlk-timeout (используется для блокирующих блокировок в базах данных в режиме wal). Метод sqlite3_busy_timeout() устанавливает оба значения, а эта функция устанавливает только setlk-timeout. Поэтому, чтобы настроить отдельные значения busy-timeout и setlk-timeout для одного дескриптора базы данных, вызовите sqlite3_busy_timeout(), а затем эту функцию.

Когда число подключений к базе данных в режиме wal уменьшается с 1 до 0, последнее подключение устанавливает эксклюзивную блокировку базы данных, а затем выполняет контрольную точку и удаляет файл wal. Пока это происходит, любое новое подключение, пытающееся прочитать данные из базы, завершается ошибкой SQLITE_BUSY. Если же этому API передан флаг SQLITE_SETLK_BLOCK_ON_CONNECT, новое подключение блокируется до снятия эксклюзивной блокировки.

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

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

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

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

Уничтожение снимка

void sqlite3_snapshot_free(sqlite3_snapshot*);

Интерфейс sqlite3_snapshot_free(P) уничтожает sqlite3_snapshot P. Чтобы избежать утечки памяти, приложение должно в конечном итоге освободить каждый объект sqlite3_snapshot с помощью этой процедуры.

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

Создание снимка базы данных

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

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

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

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

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

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

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

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

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

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

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

Начало транзакции чтения для исторического снимка

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

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

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

Вызов 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.

Восстановление снимков из файла wal

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_step() возвращала значение, отличное от SQLITE_ROW, требовался вызов sqlite3_reset() перед любым последующим вызовом sqlite3_step(). Если не сбросить подготовленный оператор с помощью sqlite3_reset(), вызов sqlite3_step() возвращал бы SQLITE_MISUSE. Однако начиная с версии 3.6.23.1 (2010-03-26) 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 нельзя изменить, пока оператор активен. Поэтому перед вызовом sqlite3_stmt_explain(S,E) рекомендуется вызывать sqlite3_reset(S).

Запрос настройки 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, приводят к тому, что sqlite3_stmt_readonly() возвращает true, поскольку сами операторы фактически не изменяют базу данных, а управляют моментом внесения изменений другими операторами. Операторы ATTACH и DETACH также приводят к тому, что sqlite3_stmt_readonly() возвращает true: хотя они меняют конфигурацию подключения к базе данных, они не изменяют содержимое файлов баз данных на диске. Интерфейс sqlite3_stmt_readonly() возвращает true для BEGIN, поскольку BEGIN лишь устанавливает внутренние флаги, но команды BEGIN IMMEDIATE и BEGIN EXCLUSIVE обращаются к базе данных, поэтому sqlite3_stmt_readonly() возвращает для них false.

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

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

Обнуление счётчиков состояния сканирования

void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);

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

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

Состояние подготовленного оператора

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

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

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

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

Создание нового объекта динамической строки

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.

Сопоставление строк с шаблоном GLOB

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

Дополнительные сведения см. в документации о режимах многопоточности.

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

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

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

Эту проблему можно обойти, проверив расширенный код ошибки, возвращённый вызовом sqlite3_step(). Если имеется блокирующее соединение, расширенный код ошибки равен SQLITE_LOCKED_SHAREDCACHE. В особом случае "DROP TABLE/INDEX" расширенный код ошибки равен просто SQLITE_LOCKED.

Функции обратного вызова для уведомления об изменении данных

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

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

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

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

Каждая функция 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", расположены рядом. Этот режим используется, когда планировщик запросов выполняет GROUP BY.

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

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

Ограничение виртуальной таблицы вида "column 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 по одному значению за раз. Если выполнены оба условия, параметр метода xFilter с индексом argvIndex будет иметь тип 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 — индекс с отсчётом от нуля в 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, является защищённым sqlite3_value и действителен в течение всего времени вызова метода xBestIndex. После возврата из xBestIndex объект sqlite3_value, возвращённый sqlite3_vtab_rhs_value(), автоматически освобождается.

"_rhs_" в названии этой процедуры — сокращение от "Right-Hand Side" («правая часть»).

Настройка автоматической контрольной точки

int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

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

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

Для вызова этого интерфейса из SQL можно использовать прагму wal_autocheckpoint.

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

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

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

Выполнение контрольной точки базы данных

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

Вызов sqlite3_wal_checkpoint(D,X) эквивалентен вызову sqlite3_wal_checkpoint_v2(D,X,SQLITE_CHECKPOINT_PASSIVE,0,0).

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

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

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

SQLITE_CHECKPOINT_FULL

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

SQLITE_CHECKPOINT_RESTART

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

SQLITE_CHECKPOINT_TRUNCATE

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

SQLITE_CHECKPOINT_NOOP

В этом режиме всегда обрабатывается ноль кадров. Единственная причина для вызова контрольной точки NOOP — получение значений, возвращаемых sqlite3_wal_checkpoint_v2(), через выходные параметры *pnLog и *pnCkpt.

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

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

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

Если параметр zDb равен NULL или указывает на строку нулевой длины, указанная операция выполняется для всех WAL-баз данных, присоединённых к подключению к базе данных db. В этом случае значения, записанные в выходные параметры *pnLog и *pnCkpt, не определены. Если при обработке одной или нескольких присоединённых WAL-баз данных возникает ошибка SQLITE_BUSY, операция всё равно выполняется для остальных присоединённых баз данных, а в конце возвращается 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().

Для вызова этого интерфейса из SQL можно использовать команду PRAGMA wal_checkpoint.

Обратный вызов фиксации журнала предварительной записи

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

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

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

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

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

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

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

И интерфейс sqlite3_wal_autocheckpoint(), и прагма wal_autocheckpoint вызывают sqlite3_wal_hook() и перезаписывают любые предыдущие настройки sqlite3_wal_hook().

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

Передача указателя NULL для обратного вызова полностью отключает автоматические контрольные точки. Чтобы восстановить поведение по умолчанию, вызовите sqlite3_wal_autocheckpoint(db,1000) или используйте PRAGMA wal_checkpoint.

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

#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_ERROR_RESERVESIZE       (SQLITE_ERROR | (4<<8))
#define SQLITE_ERROR_KEY               (SQLITE_ERROR | (5<<8))
#define SQLITE_ERROR_UNABLE            (SQLITE_ERROR | (6<<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_IOERR_BADKEY            (SQLITE_IOERR | (35<<8))
#define SQLITE_IOERR_CODEC             (SQLITE_IOERR | (36<<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 only */

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

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

#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 */
#define SQLITE_UTF8_ZT       16    /* Zero-terminated UTF8 */

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

SQLITE_UTF8

Текст закодирован в UTF-8

SQLITE_UTF16LE

Текст закодирован в UTF-16; каждая кодовая точка представлена в порядке байтов «от младшего к старшему» — сначала идёт младший байт. Например, это стандартная кодировка в Windows.

SQLITE_UTF16BE

Текст закодирован в UTF-16; каждая кодовая точка представлена в порядке байтов «от старшего к младшему» — сначала идёт старший байт. Эта кодировка встречается реже, но всё ещё используется, особенно в старых системах.

SQLITE_UTF16

Текст закодирован в UTF-16; каждая кодовая точка представлена в порядке байтов от младшего к старшему или от старшего к младшему в соответствии с порядком байтов на компьютере.

SQLITE_ANY

Это значение кодировки можно использовать только для объявления предпочтительной кодировки текста для определяемых приложением SQL-функций, созданных с помощью sqlite3_create_function() и подобных функций. Если предпочтительная кодировка (четвёртый параметр sqlite3_create_function() — параметр eTextRep) равна SQLITE_ANY, это означает, что функция не отдаёт предпочтения какой-либо кодировке текста своих параметров и может принимать текст в любой кодировке, которую ядро SQLite сочтёт удобным предоставить. Этот параметр устарел. Не используйте его в новых приложениях.

SQLITE_UTF16_ALIGNED

Это значение кодировки можно использовать в качестве третьего параметра (параметра eTextRep) для sqlite3_create_collation() и подобных функций. Оно означает, что созданная определяемая приложением последовательность сортировки ожидает входные строки в кодировке UTF-16 с порядком байтов, принятым в системе, и что начало строк должно быть выровнено по границе в 2 байта.

SQLITE_UTF8_ZT

Этот параметр можно использовать только для указания кодировки текста строк, передаваемых в sqlite3_result_text64() и sqlite3_bind_text64(). Кодировка SQLITE_UTF8_ZT означает, что входная строка (назовём её "z") закодирована в UTF-8 и завершается нулевым байтом. Если параметр длины (назовём его "n") неотрицателен, этот параметр кодировки означает, что вызывающая сторона гарантирует наличие в массиве z не менее n+1 байта и что байт z[n] имеет нулевое значение. Этот параметр даёт тот же результат, что и SQLITE_UTF8, но в некоторых случаях повышает эффективность, позволяя избежать необходимости копировать входную строку. Однако если для z выделено меньше n+1 байта или байт z[n] не равен нулю, поведение не определено.

Базовые типы данных

#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-разрядное целое число
• число с плавающей точкой IEEE, 64-разрядное
• строка
• BLOB
• NULL

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

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

Типы данных для табличной функции CARRAY

#define SQLITE_CARRAY_INT32     0    /* Data is 32-bit signed integers */
#define SQLITE_CARRAY_INT64     1    /* Data is 64-bit signed integers */
#define SQLITE_CARRAY_DOUBLE    2    /* Data is doubles */
#define SQLITE_CARRAY_TEXT      3    /* Data is char* */
#define SQLITE_CARRAY_BLOB      4    /* Data is struct iovec */

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

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

#define SQLITE_CHECKPOINT_NOOP    -1  /* Do no work at all */
#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_ERROR, если вызвать ее с параметром конфигурации SQLITE_CONFIG_SINGLETHREAD.

SQLITE_CONFIG_MULTITHREAD

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

SQLITE_CONFIG_SERIALIZED

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

SQLITE_CONFIG_MALLOC

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

SQLITE_CONFIG_GETMALLOC

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

SQLITE_CONFIG_SMALL_MALLOC

Параметр SQLITE_CONFIG_SMALL_MALLOC принимает один аргумент типа int, интерпретируемый как логическое значение. Если он равен true, то сообщает 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 скомпилирована с параметром 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 должен быть либо нулевым указателем, либо указателем на блок памяти размером не менее sz*N байт, выровненный по 8-байтовой границе; в противном случае дальнейшее поведение не определено. Если pMem не равен NULL, SQLite будет стараться использовать предоставленную память для нужд кэша страниц, переходя к sqlite3_malloc(), если строка кэша страниц превышает sz байт или весь буфер pMem исчерпан. Если pMem равен NULL, а N не равен нулю, каждое подключение к базе данных выполняет первоначальное массовое выделение памяти для кэша страниц с помощью sqlite3_malloc() в объеме, достаточном для N строк кэша, если N положителен, или для -1024*N байт, если N отрицателен. Если требуется дополнительная память для кэша страниц сверх объема, выделенного первоначально, SQLite отдельно вызывает sqlite3_malloc() для каждой дополнительной строки кэша.

SQLITE_CONFIG_HEAP

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

SQLITE_CONFIG_MUTEX

Параметр SQLITE_CONFIG_MUTEX принимает один аргумент — указатель на экземпляр структуры sqlite3_mutex_methods. Аргумент задает альтернативные низкоуровневые процедуры работы с мьютексами, которые будут использоваться вместо встроенных в SQLite процедур работы с мьютексами. Перед возвратом из вызова sqlite3_config() SQLite копирует содержимое структуры sqlite3_mutex_methods. Если 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 («sz»), второй — число слотов, выделяемых для каждого подключения к базе данных («cnt»). SQLITE_CONFIG_LOOKASIDE задает размер lookaside по умолчанию. Параметр SQLITE_DBCONFIG_LOOKASIDE интерфейса sqlite3_db_config() можно использовать для изменения конфигурации lookaside отдельных подключений. Параметр -DSQLITE_DEFAULT_LOOKASIDE можно использовать для изменения конфигурации 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 глобально отключена, имена файлов интерпретируются как URI только в том случае, если при открытии подключения к базе данных установлен флаг SQLITE_OPEN_URI. По умолчанию обработка URI глобально отключена. Значение по умолчанию можно изменить, скомпилировав программу с определенным символом SQLITE_USE_URI.

SQLITE_CONFIG_COVERING_INDEX_SCAN

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

SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE

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

SQLITE_CONFIG_SQLLOG

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

SQLITE_CONFIG_MMAP_SIZE

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

SQLITE_CONFIG_WIN32_HEAPSIZE

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

SQLITE_CONFIG_PCACHE_HDRSZ

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

SQLITE_CONFIG_PMASZ

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

SQLITE_CONFIG_STMTJRNL_SPILL

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

SQLITE_CONFIG_SORTERREF_SIZE

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

SQLITE_CONFIG_MEMDB_MAXSIZE

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

SQLITE_CONFIG_ROWID_IN_VIEW

Параметр SQLITE_CONFIG_ROWID_IN_VIEW включает или отключает возможность наличия ROWID у представлений (VIEW). Эту возможность можно включить, только если 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_ENABLE_ATTACH_CREATE  1020 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE   1021 /* int int* */
#define SQLITE_DBCONFIG_ENABLE_COMMENTS       1022 /* int int* */
#define SQLITE_DBCONFIG_FP_DIGITS             1023 /* int int* */
#define SQLITE_DBCONFIG_MAX                   1023 /* Largest DBCONFIG */

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

Интерфейс sqlite3_db_config() является функцией с переменным числом аргументов. Она принимает переменное число параметров, но всегда не менее двух. Число параметров, передаваемых в sqlite3_db_config(), зависит от того, какая из этих констант указана в качестве второго параметра. На этой странице документации параметры, следующие за вторым, называются «аргументами». Таким образом, выражение «N-й аргумент» на этой странице означает «N-й параметр после параметра конфигурации» или «(N+2)-й параметр sqlite3_db_config()».

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

SQLITE_DBCONFIG_LOOKASIDE

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

1. Первый аргумент ("buf") — это указатель на буфер памяти, используемый для памяти lookaside. Первый аргумент может быть равен NULL, и в этом случае SQLite выделит буфер lookaside самостоятельно с помощью sqlite3_malloc().

2. Второй аргумент ("sz") — размер каждого слота буфера lookaside. Lookaside отключается, если "sz" меньше 8. Аргумент "sz" должен быть кратен 8 и меньше 65536. Если "sz" не удовлетворяет этому ограничению, его значение уменьшается до тех пор, пока оно не начнёт ему удовлетворять.

3. Третий аргумент ("cnt") — количество слотов. Lookaside отключается, если "cnt" меньше 1. Произведение "sz" и "cnt" не должно превышать 2,147,418,112. Параметр "cnt" обычно выбирают так, чтобы произведение "sz" и "cnt" было меньше 1,000,000.

Если аргумент "buf" не равен NULL, он должен указывать на буфер памяти размером не меньше произведения "sz" и "cnt". Буфер должен быть выровнен по границе 8 байт. Конфигурацию памяти lookaside для подключения к базе данных можно изменить, только если это подключение в данный момент не использует память lookaside, то есть если значение, возвращаемое SQLITE_DBSTATUS_LOOKASIDE_USED, равно нулю. Любая попытка изменить конфигурацию памяти lookaside во время её использования оставляет конфигурацию неизменной и возвращает SQLITE_BUSY. Если аргумент "buf" равен NULL и попытка выделить память на основе значений "sz" и "cnt" завершается неудачей, lookaside отключается без уведомления.

Параметр конфигурации SQLITE_CONFIG_LOOKASIDE можно использовать, чтобы задать конфигурацию lookaside по умолчанию при инициализации. Параметр -DSQLITE_DEFAULT_LOOKASIDE можно использовать, чтобы задать конфигурацию lookaside по умолчанию во время компиляции. Типичные значения для lookaside: 1200 для "sz" и от 40 до 100 для "cnt".

SQLITE_DBCONFIG_ENABLE_FKEY

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

SQLITE_DBCONFIG_ENABLE_TRIGGER

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

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

SQLITE_DBCONFIG_ENABLE_VIEW

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

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

SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

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

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() после этого вызова. Второй параметр может быть нулевым указателем; в этом случае новая настройка не возвращается.

SQLITE_DBCONFIG_MAINDBNAME

Этот параметр используется для изменения имени схемы базы данных "main". Параметр не использует обычный формат аргументов SQLITE_DBCONFIG. Он принимает ровно один дополнительный аргумент, поэтому вызов sqlite3_db_config() содержит всего три параметра. Дополнительный аргумент должен быть указателем на константную строку в кодировке UTF8, которая станет новым именем схемы вместо "main". SQLite не создаёт копию строки с новым именем основной схемы, поэтому приложение должно гарантировать, что аргумент, переданный в SQLITE_DBCONFIG MAINDBNAME, не изменится до закрытия подключения к базе данных.

SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

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

SQLITE_DBCONFIG_ENABLE_QPSG

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

SQLITE_DBCONFIG_TRIGGER_EQP

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

SQLITE_DBCONFIG_RESET_DATABASE

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

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 включает или отключает флаг "defensive" для подключения к базе данных. Если флаг 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 включает или отключает флаг устаревшего формата файла. Если этот флаг включён, всем вновь создаваемым файлам баз данных присваивается номер версии формата схемы, равный 1 (4-байтовое целое число по смещению 44 в заголовке базы данных). Это означает, что полученный файл базы данных будет доступен для чтения и записи во всех версиях 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() и столбцами nexec и ncycle виртуальной таблицы байткода. Чтобы статистика собиралась, флаг должен быть установлен в дескрипторе базы данных как при подготовке оператора SQL, так и при его выполнении. По умолчанию флаг установлен (сбор статистики включён).

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

SQLITE_DBCONFIG_REVERSE_SCANORDER

Параметр SQLITE_DBCONFIG_REVERSE_SCANORDER меняет порядок сканирования таблиц и индексов по умолчанию: сканирование начинается с конца и движется к началу, а не наоборот. Установка SQLITE_DBCONFIG_REVERSE_SCANORDER эквивалентна установке PRAGMA reverse_unordered_selects.

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

SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE

Параметр SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE включает или отключает возможность SQL-команды ATTACH DATABASE создать новый файл базы данных, если файл базы данных, указанный в команде ATTACH, ещё не существует. По умолчанию команда ATTACH может создавать новые базы данных. Приложения могут отключить или снова включить возможность создавать новые файлы баз данных с помощью этого параметра DBCONFIG.

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

SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE

Параметр SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE включает или отключает возможность SQL-команды ATTACH DATABASE открывать базу данных для записи. По умолчанию эта возможность включена. Приложения могут отключить или снова включить её с помощью текущего параметра DBCONFIG. Если эта возможность отключена, команда ATTACH продолжит работать, но база данных будет открыта только для чтения. Если этот параметр отключён, возможность создавать новую базу данных с помощью ATTACH также отключается независимо от значения параметра SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE.

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

SQLITE_DBCONFIG_ENABLE_COMMENTS

Параметр SQLITE_DBCONFIG_ENABLE_COMMENTS включает или отключает возможность добавлять комментарии в текст SQL. По умолчанию комментарии разрешены. Приложение может отключить или снова включить комментарии в тексте SQL с помощью этого параметра DBCONFIG.

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

SQLITE_DBCONFIG_FP_DIGITS

Настройка SQLITE_DBCONFIG_FP_DIGITS — небольшое целое число, определяющее количество значащих цифр, которые SQLite будет пытаться сохранить при преобразовании чисел с плавающей точкой (тип "double" стандарта IEEE 754) в текст. Значение по умолчанию — 17 в SQLite версии 3.52.0. Во всех предыдущих версиях оно было равно 15.

Этот параметр принимает два аргумента: целое число и указатель на целое число. Первый аргумент — небольшое целое число от 3 до 23 включительно либо ноль. Настройка FP_DIGITS принимает это небольшое целое число или остаётся без изменений, если первый аргумент равен нулю или находится вне допустимого диапазона. Второй аргумент — указатель на целое число. Если указатель не равен NULL, значение настройки FP_DIGITS после возможного изменения первым аргументом записывается в целое число, на которое указывает второй аргумент.

Аргументы параметров SQLITE_DBCONFIG

Большинство параметров SQLITE_DBCONFIG принимают два аргумента, поэтому полный вызов sqlite3_db_config() содержит всего четыре параметра. Первый аргумент (третий параметр sqlite3_db_config()) — целое число. Второй аргумент — указатель на целое число. Если первый аргумент равен 1, параметр включается. Если первый аргумент равен 0, параметр отключается. Если первый аргумент равен -1, настройка параметра не изменяется. Второй аргумент, указатель на целое число, может быть равен NULL. Если второй аргумент не равен NULL, в целое число, на которое он указывает, записывается 0 или 1 в зависимости от того, отключена или включена настройка после применения изменений, заданных первым аргументом.

Хотя большинство параметров SQLITE_DBCONFIG используют формат аргументов, описанный в предыдущем абзаце, параметры SQLITE_DBCONFIG_MAINDBNAME, SQLITE_DBCONFIG_LOOKASIDE и SQLITE_DBCONFIG_FP_DIGITS устроены иначе. Подробности см. в документации по этим исключительным параметрам.

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

#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 верхнего уровня, но нельзя использовать в VIEW или TRIGGER, а также в структурах схемы, таких как ограничения CHECK, предложения DEFAULT, индексы по выражениям, частичные индексы или генерируемые столбцы.

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

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

SQLITE_INNOCUOUS

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

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

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

SQLITE_SUBTYPE

Флаг SQLITE_SUBTYPE сообщает SQLite, что функция может вызывать sqlite3_value_subtype() для проверки подтипов своих аргументов. Этот флаг предписывает 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 указывает, что функция является агрегатной и самостоятельно упорядочивает значения, переданные первым аргументом. Для вызова этой функции можно использовать синтаксис агрегатной функции упорядоченного набора с одним элементом 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
#define SQLITE_FCNTL_NULL_IO                43
#define SQLITE_FCNTL_BLOCK_ON_CONNECT       44
#define SQLITE_FCNTL_FILESTAT               45

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

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

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

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

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

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

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

• Элемент управления файлами SQLITE_FCNTL_SYNC_OMITTED больше не используется.

• Код операции 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* указателем NULL. Этот элемент управления файлами предназначен только для диагностики.

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

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

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

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

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

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

• Код операции 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: при попытке получить файловую блокировку с помощью методов xLock или xShmLock VFS должна ожидать до M миллисекунд, прежде чем сообщить об ошибке. Параметр — указатель на знаковое 32-разрядное целое число, содержащее значение, которое следует присвоить M. Перед возвратом в это знаковое 32-разрядное целое число записывается предыдущее значение M.

• Код операции SQLITE_FCNTL_BLOCK_ON_CONNECT используется для настройки VFS на ожидание при получении блокировки SHARED для подключения к базе данных в режиме WAL. Это используется для реализации функциональности, связанной с SQLITE_SETLK_BLOCK_ON_CONNECT.

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

• Код операции SQLITE_FCNTL_FILESTAT возвращает низкоуровневые диагностические сведения об объектах sqlite3_file, используемых для доступа к файлам базы данных и журнала для указанной схемы. Четвёртый параметр sqlite3_file_control() должен быть инициализированным указателем sqlite3_str. К нему добавляется текст JSON с описанием различных аспектов объекта sqlite3_file. Код операции SQLITE_FCNTL_FILESTAT обычно ничего не делает, если только его не включили с помощью параметров компиляции.

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

#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
#define SQLITE_IOCAP_SUBPAGE_READ           0x00008000

Метод 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.

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

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

#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() можно использовать только флаги, отмеченные как "Ok for 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
#define SQLITE_PREPARE_DONT_LOG                0x10
#define SQLITE_PREPARE_FROM_DDL                0x20

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

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

SQLITE_PREPARE_PERSISTENT

Флаг SQLITE_PREPARE_PERSISTENT служит подсказкой планировщику запросов о том, что подготовленная инструкция будет храниться долго и, вероятно, использоваться многократно. Без этого флага sqlite3_prepare_v3() и sqlite3_prepare16_v3() предполагают, что подготовленная инструкция будет использована один раз или, в крайнем случае, несколько раз, а затем вскоре уничтожена с помощью sqlite3_finalize(). Текущая реализация использует эту подсказку, избегая применения памяти lookaside, чтобы не истощать ограниченный запас такой памяти. В будущих версиях SQLite эта подсказка может обрабатываться иначе.

SQLITE_PREPARE_NORMALIZE

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

SQLITE_PREPARE_NO_VTAB

Флаг SQLITE_PREPARE_NO_VTAB заставляет компилятор SQL возвращать ошибку (код ошибки SQLITE_ERROR), если инструкция использует какие-либо виртуальные таблицы.

SQLITE_PREPARE_DONT_LOG

Флаг SQLITE_PREPARE_DONT_LOG запрещает отправлять ошибки компилятора SQL в журнал ошибок, заданный с помощью SQLITE_CONFIG_LOG. Например, его можно использовать для пробной компиляции, чтобы проверить корректность синтаксиса SQL, не создавая сообщений в глобальном журнале ошибок, если проверка не пройдена. Если пробная компиляция завершается неудачно, вызов sqlite3_prepare_v3() возвращает те же сведения об ошибке независимо от наличия этого флага; он лишь пропускает вызов sqlite3_log(), который записывает ошибку в журнал.

SQLITE_PREPARE_FROM_DDL

Флаг SQLITE_PREPARE_FROM_DDL заставляет компилятор SQL применять ограничения безопасности, которые в противном случае применялись бы только при разборе схемы базы данных. Иными словами, этот флаг заставляет компилятор SQL обрабатывать подготавливаемую инструкцию так, как если бы она поступила от злоумышленника. Если используется SQLITE_PREPARE_FROM_DDL и параметр SQLITE_DBCONFIG_TRUSTED_SCHEMA отключен, вызывать можно только функции SQL, помеченные флагом SQLITE_INNOCUOUS, а использовать можно только виртуальные таблицы, помеченные флагом SQLITE_VTAB_INNOCUOUS. Рекомендуется использовать параметр SQLITE_PREPARE_FROM_DDL при подготовке любого SQL-кода, сформированного на основе частей схемы базы данных. В частности, реализации виртуальных таблиц, выполняющие инструкции SQL, сформированные на основе аргументов инструкции CREATE VIRTUAL TABLE, всегда должны использовать sqlite3_prepare_v3() и устанавливать флаг SQLITE_PREPARE_FROM_DDL, чтобы предотвратить обход проверок безопасности SQLITE_DBCONFIG_TRUSTED_SCHEMA.

Состояние сканирования подготовленной инструкции

#define SQLITE_SCANSTAT_COMPLEX 0x0001

Коды операций состояния сканирования подготовленной инструкции

#define SQLITE_SCANSTAT_NLOOP    0
#define SQLITE_SCANSTAT_NVISIT   1
#define SQLITE_SCANSTAT_EST      2
#define SQLITE_SCANSTAT_NAME     3
#define SQLITE_SCANSTAT_EXPLAIN  4
#define SQLITE_SCANSTAT_SELECTID 5
#define SQLITE_SCANSTAT_PARENTID 6
#define SQLITE_SCANSTAT_NCYCLE   7

Следующие константы можно использовать в качестве параметра T интерфейса sqlite3_stmt_scanstatus(S,X,T,V). Каждая константа обозначает отдельную метрику, которую возвращает sqlite3_stmt_scanstatus().

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

Не все значения доступны для всех элементов запроса. Если значение недоступно, выходная переменная устанавливается в -1, если значение числовое, или в NULL, если оно является строкой (SQLITE_SCANSTAT_NAME).

SQLITE_SCANSTAT_NLOOP

Переменная sqlite3_int64, на которую указывает параметр V, будет установлена в общее количество выполнений цикла X.

SQLITE_SCANSTAT_NVISIT

Переменная sqlite3_int64, на которую указывает параметр V, будет установлена в общее количество строк, просмотренных всеми итерациями цикла X.

SQLITE_SCANSTAT_EST

Переменная типа "double", на которую указывает параметр V, будет установлена в оценку планировщика запросов для среднего количества строк, возвращаемых каждой итерацией цикла X. Если оценка планировщика запросов точна, это значение будет примерно равно частному NVISIT/NLOOP, а произведение этого значения для всех предшествующих циклов с тем же SELECTID будет равно значению NLOOP для текущего цикла.

SQLITE_SCANSTAT_NAME

Переменная типа "const char *", на которую указывает параметр V, будет установлена в завершающуюся нулем строку UTF-8 с именем индекса или таблицы, используемых циклом X.

SQLITE_SCANSTAT_EXPLAIN

Переменная типа "const char *", на которую указывает параметр V, будет установлена в завершающуюся нулем строку UTF-8 с описанием EXPLAIN QUERY PLAN для цикла X.

SQLITE_SCANSTAT_SELECTID

Переменная типа "int", на которую указывает параметр V, будет установлена в идентификатор элемента плана запроса X. Значение идентификатора уникально в пределах инструкции. Идентификатор выборки совпадает со значением, выводимым в первом столбце запроса EXPLAIN QUERY PLAN.

SQLITE_SCANSTAT_PARENTID

Переменная типа "int", на которую указывает параметр V, будет установлена в идентификатор родительского элемента текущего запроса, если он есть, или в ноль, если у элемента запроса нет родителя. Это то же значение, которое возвращается во втором столбце запроса EXPLAIN QUERY PLAN.

SQLITE_SCANSTAT_NCYCLE

Выходное значение sqlite3_int64 устанавливается в количество тактов, прошедших во время обработки элемента запроса согласно счетчику временных меток процессора. Это значение доступно не для всех элементов запроса; если оно недоступно, выходная переменная устанавливается в -1.

Номера версий библиотеки на этапе компиляции

#define SQLITE_VERSION        "3.53.0"
#define SQLITE_VERSION_NUMBER 3053000
#define SQLITE_SOURCE_ID      "2026-04-09 11:41:38 4525003a53a7fc63ca75c59b22c79608659ca12f0131f52c18637f829977f20b"
#define SQLITE_SCM_BRANCH     "trunk"
#define SQLITE_SCM_TAGS       "release major-release version-3.53.0"
#define SQLITE_SCM_DATETIME   "2026-04-09T11:41:38.498Z"

Макрос препроцессора C SQLITE_VERSION в заголовочном файле sqlite3.h раскрывается в строковый литерал с версией SQLite в формате "X.Y.Z", где X — номер основной версии (для SQLite3 всегда равен 3), 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().

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

#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 невозможно.

Константы, определяющие особое поведение деструктора

typedef void (*sqlite3_destructor_type)(void*);
#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)

Это специальные значения для деструктора, передаваемого в качестве последнего аргумента таким функциям, как sqlite3_result_blob(). Если аргумент деструктора равен SQLITE_STATIC, это означает, что указатель на содержимое является константным и никогда не изменится. Уничтожать его не требуется. Значение SQLITE_TRANSIENT означает, что содержимое, вероятно, скоро изменится и SQLite должна создать собственную копию содержимого до возврата.

Определение типа необходимо для обхода проблем в некоторых компиляторах C++.

Параметры состояния

#define SQLITE_STATUS_MEMORY_USED          0
#define SQLITE_STATUS_PAGECACHE_USED       1
#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
#define SQLITE_STATUS_SCRATCH_USED         3  /* NOT USED */
#define SQLITE_STATUS_SCRATCH_OVERFLOW     4  /* NOT USED */
#define SQLITE_STATUS_MALLOC_SIZE          5
#define SQLITE_STATUS_PARSER_STACK         6
#define SQLITE_STATUS_PAGECACHE_SIZE       7
#define SQLITE_STATUS_SCRATCH_SIZE         8  /* NOT USED */
#define SQLITE_STATUS_MALLOC_COUNT         9

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

SQLITE_STATUS_MEMORY_USED

Этот параметр задает текущий объем памяти, выделенной с помощью sqlite3_malloc() прямо или косвенно. Значение включает вызовы sqlite3_malloc(), выполненные приложением, и внутреннее использование памяти библиотекой SQLite. Вспомогательная память кэша страниц, управляемая параметром SQLITE_CONFIG_PAGECACHE, в это значение не входит. Возвращаемое значение представляет собой сумму размеров выделенных блоков, сообщаемых методом xSize в sqlite3_mem_methods.

SQLITE_STATUS_MALLOC_SIZE

Этот параметр хранит самый большой запрос на выделение памяти, переданный функциям sqlite3_malloc() или sqlite3_realloc() (либо их внутренним эквивалентам). Интерес представляет только значение, возвращаемое в параметре *pHighwater функции sqlite3_status(). Значение, записанное в параметр *pCurrent, не определено.

SQLITE_STATUS_MALLOC_COUNT

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

SQLITE_STATUS_PAGECACHE_USED

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

SQLITE_STATUS_PAGECACHE_OVERFLOW

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

SQLITE_STATUS_PAGECACHE_SIZE

Этот параметр хранит самый большой запрос на выделение памяти, переданный распределителю памяти кэша страниц. Интерес представляет только значение, возвращаемое в параметре *pHighwater функции sqlite3_status(). Значение, записанное в параметр *pCurrent, не определено.

SQLITE_STATUS_SCRATCH_USED

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

SQLITE_STATUS_SCRATCH_OVERFLOW

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

SQLITE_STATUS_SCRATCH_SIZE

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

SQLITE_STATUS_PARSER_STACK

Параметр *pHighwater хранит максимальную глубину стека анализатора. Значение *pCurrent не определено. Значение *pHighwater имеет смысл только в том случае, если SQLite скомпилирована с параметром YYTRACKMAXSTACKDEPTH.

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

Флаги типа синхронизации

#define SQLITE_SYNC_NORMAL        0x00002
#define SQLITE_SYNC_FULL          0x00003
#define SQLITE_SYNC_DATAONLY      0x00010

При вызове SQLite метода xSync() объекта sqlite3_io_methods в качестве второго аргумента используется сочетание этих целочисленных значений.

Флаг SQLITE_SYNC_DATAONLY означает, что операция синхронизации должна сбросить на устройство хранения данных только данные. Информацию об индексных узлах сбрасывать не требуется. Если младшие четыре бита флага равны SQLITE_SYNC_NORMAL, используется обычная семантика fsync(). Если младшие четыре бита равны SQLITE_SYNC_FULL, вместо fsync() используется полная синхронизация в стиле Mac OS X.

Не путайте флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL с настройками PRAGMA synchronous=NORMAL и PRAGMA synchronous=FULL. Прагма synchronous определяет, когда вызывается метод VFS xSync, и одинаково применяется на всех платформах. Флаги SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL определяют интенсивность, строгость или принудительность операций синхронизации и имеют значение только в Mac OSX для стандартного кода SQLite. (Сторонние реализации VFS также могут различать SQLITE_SYNC_NORMAL и SQLITE_SYNC_FULL, но среди операционных систем, изначально поддерживаемых SQLite, только Mac OSX учитывает это различие.)

Коды операций тестового интерфейса

#define SQLITE_TESTCTRL_FIRST                    5
#define SQLITE_TESTCTRL_PRNG_SAVE                5
#define SQLITE_TESTCTRL_PRNG_RESTORE             6
#define SQLITE_TESTCTRL_PRNG_RESET               7  /* NOT USED */
#define SQLITE_TESTCTRL_FK_NO_ACTION             7
#define SQLITE_TESTCTRL_BITVEC_TEST              8
#define SQLITE_TESTCTRL_FAULT_INSTALL            9
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
#define SQLITE_TESTCTRL_PENDING_BYTE            11
#define SQLITE_TESTCTRL_ASSERT                  12
#define SQLITE_TESTCTRL_ALWAYS                  13
#define SQLITE_TESTCTRL_RESERVE                 14  /* NOT USED */
#define SQLITE_TESTCTRL_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_ATOF                    34
#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, указывающий на вызов триггера. Функция обратного вызова может вычислить тот же текст, который возвращал устаревший интерфейс 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, если произойдут какие-либо изменения и при этом не будет других конфликтующих параллельных транзакций записи. После выполнения ROLLBACK или COMMIT состояние транзакции вернётся к SQLITE_TXN_NONE.

SQLITE_TXN_WRITE

Состояние SQLITE_TXN_WRITE означает, что база данных в данный момент находится в транзакции записи. Данные были записаны в файл базы данных, но ещё не зафиксированы. После следующего выполнения ROLLBACK или COMMIT состояние транзакции изменится на SQLITE_TXN_NONE.

Параметры конфигурации виртуальных таблиц

#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, вся инструкция откатывается так, как если бы в пользовательской инструкции SQL было указано OR ABORT, независимо от фактически заданного режима 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
#define SQLITE_LIMIT_PARSER_DEPTH             12

Эти константы задают различные ограничения производительности, значения которых можно уменьшить во время выполнения с помощью 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_PARSER_DEPTH

Максимальная глубина стека парсера LALR(1), используемого для анализа входящих инструкций SQL.

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

Максимальная длина аргумента-шаблона операторов 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_TEMPBUF_SPILL       13
#define SQLITE_DBSTATUS_MAX                 13   /* 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

Этот параметр возвращает приблизительное количество байтов динамической памяти, используемой всеми кэшами pager, связанными с подключением к базе данных. Максимальное значение для SQLITE_DBSTATUS_CACHE_USED всегда равно 0.

SQLITE_DBSTATUS_CACHE_USED_SHARED

Этот параметр аналогичен DBSTATUS_CACHE_USED, за исключением того, что если кэш pager совместно используется двумя или более подключениями, объём используемой этим кэшем динамической памяти поровну распределяется между подключениями. Иными словами, если ни один из кэшей pager, связанных с подключением к базе данных, не является общим, этот запрос возвращает то же значение, что и DBSTATUS_CACHE_USED. Если же один или несколько кэшей pager являются общими, возвращаемое этим вызовом значение будет меньше, чем значение DBSTATUS_CACHE_USED. Максимальное значение для SQLITE_DBSTATUS_CACHE_USED_SHARED всегда равно 0.

SQLITE_DBSTATUS_SCHEMA_USED

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

SQLITE_DBSTATUS_STMT_USED

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

SQLITE_DBSTATUS_CACHE_HIT

Этот параметр возвращает количество попаданий в кэш pager. Максимальное значение для SQLITE_DBSTATUS_CACHE_HIT всегда равно 0.

SQLITE_DBSTATUS_CACHE_MISS

Этот параметр возвращает количество промахов кэша pager. Максимальное значение для SQLITE_DBSTATUS_CACHE_MISS всегда равно 0.

SQLITE_DBSTATUS_CACHE_WRITE

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

Значения, измеряемые этим параметром (SQLITE_DBSTATUS_CACHE_WRITE), и SQLITE_DBSTATUS_TEMPBUF_SPILL частично пересекаются. Сброс одного из них уменьшит значение другого.

SQLITE_DBSTATUS_CACHE_SPILL

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

SQLITE_DBSTATUS_DEFERRED_FKS

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

[SQLITE_DBSTATUS_TEMPBUF_SPILL

SQLITE_DBSTATUS_TEMPBUF_SPILL

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

Значения, измеряемые этим параметром (SQLITE_DBSTATUS_TEMPBUF_SPILL), и SQLITE_DBSTATUS_CACHE_WRITE частично пересекаются. Сброс одного из них уменьшит значение другого.

Параметры состояния подготовленных инструкций

#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 — это количество пропусков этапа соединения, вызванных тем, что фильтр Блума вернул результат «не найдено». Соответствующее значение SQLITE_STMTSTATUS_FILTER_MISS показывает, сколько раз фильтр Блума вернул результат «найдено» и поэтому этап соединения пришлось обработать обычным образом.

SQLITE_STMTSTATUS_MEMUSED

Это приблизительное количество байтов динамической памяти, используемой для хранения подготовленной инструкции. Это значение фактически не является счётчиком, поэтому параметр resetFlg функции sqlite3_stmt_status() игнорируется, если код операции — SQLITE_STMTSTATUS_MEMUSED.

Снимок базы данных

typedef struct sqlite3_snapshot {
  unsigned char hidden[48];
} sqlite3_snapshot;

Экземпляр объекта 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 включает определения typedef для 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()

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

• 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_db_status64
• 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_errmsg
• sqlite3_set_last_insert_rowid
• sqlite3_setlk_timeout
• 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()

2 деструктора, использующих этот объект: sqlite3_str_finish(), sqlite3_str_free()

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

• sqlite3_str_append
• sqlite3_str_appendall
• sqlite3_str_appendchar
• sqlite3_str_appendf
• sqlite3_str_errcode
• sqlite3_str_length
• sqlite3_str_reset
• sqlite3_str_truncate
• 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() должен возвращать количество страниц, которые в данный момент хранятся в кэше, как закрепленных, так и незакрепленных.

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

Извлекаемая страница определяется ключом. Минимальное значение ключа — 1. После извлечения с помощью xFetch страница считается «закрепленной».

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

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

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

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

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

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

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

Метод xDestroy() используется для удаления кэша, выделенного с помощью xCreate(). Необходимо освободить все ресурсы, связанные с указанным кэшем. После вызова метода xDestroy() SQLite считает дескриптор sqlite3_pcache* недействительным и больше не будет использовать его с другими функциями sqlite3_pcache_methods2.

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

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

typedef struct sqlite3_stmt sqlite3_stmt;

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

Представьте каждый оператор SQL как отдельную компьютерную программу. Исходный текст SQL — это исходный код. Объект подготовленного оператора — это скомпилированный объектный код. Прежде чем выполнить любой оператор SQL, его необходимо преобразовать в подготовленный оператор.

Обычно жизненный цикл объекта подготовленного оператора выглядит так:

1. Создать объект подготовленного оператора с помощью sqlite3_prepare_v2().
2. Привязать значения к параметрам с помощью интерфейсов sqlite3_bind_*().
3. Выполнить SQL, вызвав sqlite3_step() один или несколько раз.
4. Сбросить подготовленный оператор с помощью sqlite3_reset(), а затем вернуться к шагу 2. Повторить это ноль или более раз.
5. Уничтожить объект с помощью sqlite3_finalize().

6 конструкторов, использующих этот объект:

• sqlite3_prepare
• sqlite3_prepare16
• sqlite3_prepare16_v2
• sqlite3_prepare16_v3
• sqlite3_prepare_v2
• sqlite3_prepare_v3

1 деструктор, использующий этот объект: sqlite3_finalize()

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

• sqlite3_bind_blob
• sqlite3_bind_blob64
• sqlite3_bind_double
• sqlite3_bind_int
• sqlite3_bind_int64
• sqlite3_bind_null
• sqlite3_bind_parameter_count
• sqlite3_bind_parameter_index
• sqlite3_bind_parameter_name
• sqlite3_bind_pointer
• sqlite3_bind_text
• sqlite3_bind_text16
• sqlite3_bind_text64
• sqlite3_bind_value
• sqlite3_bind_zeroblob
• sqlite3_bind_zeroblob64
• sqlite3_clear_bindings
• sqlite3_column_blob
• sqlite3_column_bytes
• sqlite3_column_bytes16
• sqlite3_column_count
• sqlite3_column_database_name
• sqlite3_column_database_name16
• sqlite3_column_decltype
• sqlite3_column_decltype16
• sqlite3_column_double
• sqlite3_column_int
• sqlite3_column_int64
• sqlite3_column_name
• sqlite3_column_name16
• sqlite3_column_origin_name
• sqlite3_column_origin_name16
• sqlite3_column_table_name
• sqlite3_column_table_name16
• sqlite3_column_text
• sqlite3_column_text16
• sqlite3_column_type
• sqlite3_column_value
• sqlite3_data_count
• sqlite3_db_handle
• sqlite3_expanded_sql
• sqlite3_normalized_sql
• sqlite3_reset
• sqlite3_sql
• sqlite3_step
• sqlite3_stmt_busy
• sqlite3_stmt_explain
• sqlite3_stmt_isexplain
• sqlite3_stmt_readonly
• sqlite3_stmt_scanstatus
• sqlite3_stmt_scanstatus_reset
• sqlite3_stmt_scanstatus_v2
• sqlite3_stmt_status

Объект значения с динамической типизацией

typedef struct sqlite3_value sqlite3_value;

SQLite использует объект sqlite3_value для представления всех значений, которые могут храниться в таблице базы данных. Для хранимых значений SQLite использует динамическую типизацию. Значения в объектах sqlite3_value могут быть целыми числами, числами с плавающей точкой, строками, BLOB-объектами или NULL.

Объект sqlite3_value может быть «защищенным» или «незащищенным». Некоторые интерфейсы требуют защищенный sqlite3_value. Другие интерфейсы принимают как защищенный, так и незащищенный sqlite3_value. В описании каждого интерфейса, принимающего аргументы sqlite3_value, указано, требуется ли защищенный sqlite3_value. Интерфейс sqlite3_value_dup() позволяет создать новый защищенный sqlite3_value на основе незащищенного sqlite3_value.

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

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_finish() объект sqlite3_backup становится недействительным и больше не может использоваться.

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

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

Привязка значений массива к табличной функции CARRAY

int sqlite3_carray_bind_v2(
  sqlite3_stmt *pStmt,        /* Statement to be bound */
  int i,                      /* Parameter index */
  void *aData,                /* Pointer to array data */
  int nData,                  /* Number of data elements */
  int mFlags,                 /* CARRAY flags */
  void (*xDel)(void*),        /* Destructor for aData */
  void *pDel                  /* Optional argument to xDel() */
);
int sqlite3_carray_bind(
  sqlite3_stmt *pStmt,        /* Statement to be bound */
  int i,                      /* Parameter index */
  void *aData,                /* Pointer to array data */
  int nData,                  /* Number of data elements */
  int mFlags,                 /* CARRAY flags */
  void (*xDel)(void*)         /* Destructor for aData */
);

Интерфейс sqlite3_carray_bind_v2(S,I,P,N,F,X,D) привязывает значение массива к параметру, который является первым аргументом табличной функции carray(). Параметр S — это указатель на подготовленный оператор, использующий функции carray(). I — индекс привязываемого параметра. I должен быть индексом параметра, являющегося первым аргументом табличной функции carray(). P — указатель на привязываемый массив, а N — количество элементов в массиве. Аргумент F должен принимать одно из значений SQLITE_CARRAY_INT32, SQLITE_CARRAY_INT64, SQLITE_CARRAY_DOUBLE, SQLITE_CARRAY_TEXT или SQLITE_CARRAY_BLOB и указывает тип данных массива P.

Если аргумент X не является указателем NULL или одним из специальных значений SQLITE_STATIC и SQLITE_TRANSIENT, SQLite вызовет функцию X с аргументом D после завершения использования данных в P. Вызов X(D) служит деструктором массива P. Деструктор X(D) вызывается даже в том случае, если вызов sqlite3_carray_bind_v2() завершается неудачей. Если параметр X имеет специальное значение SQLITE_STATIC, SQLite считает данные статическими и никогда не вызывает деструктор. Если параметр X имеет специальное значение SQLITE_TRANSIENT, sqlite3_carray_bind_v2() создает собственную копию данных до возврата и никогда не вызывает деструктор X.

Функция sqlite3_carray_bind() работает так же, как sqlite3_carray_bind_v2(), если параметру D присвоено значение P. Иными словами, sqlite3_carray_bind(S,I,P,N,F,X) эквивалентна sqlite3_carray_bind_v2(S,I,P,N,F,X,P).

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

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

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

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

Возвращаются исходные, не переименованные с помощью псевдонимов имена базы данных, таблицы и столбца.

Первый аргумент этих интерфейсов — это подготовленный оператор. Функции возвращают информацию о N-м столбце результата, возвращаемом оператором, где N — второй аргумент функции. В этих процедурах крайний левый столбец имеет номер 0.

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

Как и для всех остальных API SQLite, функции, имена которых заканчиваются на "16", возвращают строки в кодировке UTF-16, а остальные функции — в кодировке UTF-8.

Эти API доступны только в том случае, если библиотека была скомпилирована с символом препроцессора C SQLITE_ENABLE_COLUMN_METADATA.

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

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

const char *sqlite3_column_decltype(sqlite3_stmt*,int);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

Первый параметр — это подготовленный оператор. Если этот оператор является оператором SELECT, а N-й столбец возвращаемого этим SELECT набора результатов является столбцом таблицы (а не выражением или подзапросом), возвращается объявленный тип столбца таблицы. Если N-й столбец набора результатов является выражением или подзапросом, возвращается указатель NULL. Возвращаемая строка всегда закодирована в UTF-8.

Например, для схемы базы данных:

CREATE TABLE t1(c1 VARIANT);

и следующего оператора, подлежащего компиляции:

SELECT c1 + 1, c1 FROM t1;

эта процедура вернёт строку "VARIANT" для второго столбца результата (i==1) и указатель NULL для первого столбца результата (i==0).

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

Имена столбцов в наборе результатов

const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);

Эти процедуры возвращают имя, присвоенное определённому столбцу в наборе результатов оператора SELECT. Интерфейс sqlite3_column_name() возвращает указатель на завершающуюся нулём строку UTF-8, а sqlite3_column_name16() — указатель на завершающуюся нулём строку UTF-16. Первый параметр — это подготовленный оператор, реализующий оператор SELECT. Второй параметр — номер столбца. Самый левый столбец имеет номер 0.

Возвращённый указатель на строку действителен до уничтожения подготовленного оператора с помощью sqlite3_finalize(), автоматической повторной подготовки оператора при первом вызове sqlite3_step() для конкретного выполнения или до следующего вызова sqlite3_column_name() либо sqlite3_column_name16() для того же столбца.

Если при обработке любой из этих процедур происходит сбой sqlite3_malloc() (например, во время преобразования из UTF-8 в UTF-16), возвращается указатель NULL.

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

Обратные вызовы уведомления о фиксации и откате

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

Интерфейс sqlite3_commit_hook() регистрирует функцию обратного вызова, которая вызывается при каждой фиксации транзакции. Любой обратный вызов, установленный предыдущим вызовом sqlite3_commit_hook() для того же подключения к базе данных, заменяется. Интерфейс sqlite3_rollback_hook() регистрирует функцию обратного вызова, которая вызывается при каждом откате транзакции. Любой обратный вызов, установленный предыдущим вызовом sqlite3_rollback_hook() для того же подключения к базе данных, заменяется. Аргумент pArg передаётся функции обратного вызова. Если функция обратного вызова обработчика фиксации возвращает ненулевое значение, фиксация преобразуется в откат.

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

Функции обратного вызова обработчиков фиксации и отката не являются реентерабельными. Реализация обратного вызова не должна выполнять никаких действий, изменяющих подключение к базе данных, которое вызвало этот обратный вызов. Любые действия по изменению подключения к базе данных необходимо отложить до завершения вызова sqlite3_step(), который первоначально вызвал обработчик фиксации или отката. Обратите внимание: выполнение любых других операторов SQL, включая операторы SELECT, или даже простой вызов sqlite3_prepare_v2() и sqlite3_step() изменит подключение к базе данных в смысле слова «изменить» в этом абзаце.

Регистрация функции NULL отключает обратный вызов.

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

Для целей этого 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.

Если до вызова sqlite3_complete16() SQLite не была инициализирована с помощью sqlite3_initialize(), sqlite3_complete16() автоматически вызывает sqlite3_initialize(). Если инициализация завершается с ошибкой, 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, а также массива P из N пар «ключ/значение» URI. Результат 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 указателей на строки. Каждая пара указателей в этом массиве соответствует ключу и значению параметра запроса. Если N равно нулю, параметр P может быть указателем NULL. Ни один из 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(), могут произойти неприятности, например повреждение кучи или сбой сегментации. После вызова sqlite3_free_filename(Y) значение 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_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
int sqlite3_db_status64(sqlite3*,int,sqlite3_int64*,sqlite3_int64*,int);

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

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

Процедура sqlite3_db_status() при успешном выполнении возвращает SQLITE_OK, а при ошибке — ненулевой код ошибки.

Процедура sqlite3_db_status64(D,O,C,H,R) работает точно так же, как sqlite3_db_status(D,O,C,H,R), за исключением того, что параметры C и H являются указателями на 64-разрядные целые числа (тип: sqlite3_int64), а не указателями на 32-разрядные целые числа, что позволяет возвращать более крупные значения состояния. Если значение состояния превышает 2,147,483,647, sqlite3_db_status() усечёт его, а sqlite3_db_status64() вернёт полное значение.

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

Коды и сообщения об ошибках

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_db_handle()

Функции 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 закодирован в UTF-8. Если последняя ошибка не связана с определённым токеном во входном тексте 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. VFS для Windows использует для некоторых операций собственные malloc() и free().

Подпрограмма sqlite3_malloc() возвращает указатель на блок памяти размером не менее N байт, где N — параметр. Если sqlite3_malloc() не удается получить достаточно свободной памяти, она возвращает указатель NULL. Если параметр N функции sqlite3_malloc() равен нулю или отрицателен, sqlite3_malloc() возвращает указатель NULL.

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

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

Интерфейс sqlite3_realloc(X,N) пытается изменить размер ранее выделенного блока памяти X так, чтобы он составлял не менее N байт. Если параметр X функции sqlite3_realloc(X,N) является указателем NULL, ее поведение идентично вызову 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 — указатель NULL, 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 указателей указывают на строки, завершенные нулевым символом, содержащие имена столбцов. Остальные элементы указывают на результаты запроса. Значения NULL представлены указателями NULL. Все остальные значения представлены строками UTF-8, завершенными нулевым символом, как их возвращает sqlite3_column_text().

Таблица результатов может состоять из одного или нескольких блоков памяти. Небезопасно напрямую передавать таблицу результатов в sqlite3_free(). Таблицу результатов следует освобождать с помощью sqlite3_free_table().

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

Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21

Имеются два столбца (M==2) и три строки (N==3). Таким образом, таблица результатов содержит 8 элементов. Предположим, что таблица результатов хранится в массиве с именем azResult. Тогда azResult содержит следующие данные:

azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";

Функция sqlite3_get_table() вычисляет один или несколько разделенных точкой с запятой операторов SQL из строки UTF-8, завершенной нулевым символом, переданной во втором параметре, и возвращает таблицу результатов через указатель, заданный третьим параметром.

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

Интерфейс sqlite3_set_auxdata(C,N,P,X) сохраняет P в качестве вспомогательных данных для N-го аргумента функции, определенной приложением. Последующие вызовы sqlite3_get_auxdata(C,N) возвращают P из последнего вызова sqlite3_set_auxdata(C,N,P,X), если вспомогательные данные еще действительны, или NULL, если они были удалены. После каждого вызова sqlite3_set_auxdata(C,N,P,X), в котором X не равен NULL, SQLite ровно один раз вызовет функцию-деструктор X с параметром P, когда вспомогательные данные будут удалены. SQLite может удалить вспомогательные данные в любое время, в том числе:

• при изменении соответствующего параметра функции;
• при вызове sqlite3_reset() или sqlite3_finalize() для оператора SQL;
• при повторном вызове sqlite3_set_auxdata() для того же параметра;
• во время исходного вызова sqlite3_set_auxdata(), если произошла ошибка выделения памяти;
• во время исходного вызова sqlite3_set_auxdata(), если функция вычисляется при планировании запроса, а не при его выполнении, как иногда происходит при использовании SQLITE_ENABLE_STAT4.

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

Если 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_shutdown(). Инициализацию выполняет только эффективный вызов sqlite3_initialize(). Все остальные вызовы безвредны и ничего не делают.

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

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

Помимо прочего, 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, в будущем может стать стандартным.

Подпрограмма 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().

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

Прерванная операция SQL возвращает SQLITE_INTERRUPT. Если прерванная операция SQL является INSERT, UPDATE или DELETE внутри явной транзакции, вся транзакция автоматически откатывается.

Вызов sqlite3_interrupt(D) действует, пока не завершатся все выполняющиеся в данный момент операторы SQL для соединения с базой данных D. Любые новые операторы SQL, запущенные после вызова sqlite3_interrupt() и до того, как счетчик выполняющихся операторов достигнет нуля, будут прерваны, как если бы они выполнялись до вызова sqlite3_interrupt(). Новые операторы SQL, запущенные после того, как счетчик выполняющихся операторов достигнет нуля, не затрагиваются вызовом sqlite3_interrupt(). Вызов 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 допускает некоторые вольности. Часто ключевое слово можно использовать как идентификатор, если это не приводит к неоднозначности разбора. Например, SQLite принимает оператор "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" и создает новую таблицу с именем "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);

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

См. также: sqlite_version() и sqlite_source_id().

Статистика распределителя памяти

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

SQLite предоставляет эти два интерфейса для получения сведений о состоянии подпрограмм sqlite3_malloc(), sqlite3_free() и sqlite3_realloc(), образующих встроенную подсистему выделения памяти.

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

Мьютексы

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.

Процедура 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. Это кажется нелогичным, поскольку очевидно, что несуществующий мьютекс не может быть занят. Но мьютекс не существует потому, что сборка не использует мьютексы. Мы не хотим, чтобы оператор assert(), содержащий вызов sqlite3_mutex_held(), завершался неудачей, поэтому уместно вернуть ненулевое значение. Интерфейс sqlite3_mutex_notheld() также должен возвращать 1, если ему передан указатель NULL.

Открытие нового подключения к базе данных

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

Эти процедуры открывают файл базы данных SQLite, указанный аргументом filename. Аргумент filename интерпретируется как UTF-8 в sqlite3_open() и sqlite3_open_v2(), а в sqlite3_open16() — как UTF-16 в естественном порядке байтов. Дескриптор подключения к базе данных обычно возвращается в *ppDb, даже если возникает ошибка. Единственное исключение — ситуация, когда SQLite не может выделить память для объекта sqlite3: в этом случае в *ppDb записывается NULL вместо указателя на объект sqlite3. Если база данных успешно открыта (и/или создана), возвращается SQLITE_OK. В противном случае возвращается код ошибки. После сбоя любой из процедур sqlite3_open() для получения описания ошибки на английском языке можно использовать процедуры sqlite3_errmsg() или sqlite3_errmsg16().

Для баз данных, созданных с помощью sqlite3_open() или sqlite3_open_v2(), кодировкой по умолчанию будет UTF-8. Для баз данных, созданных с помощью 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

Для нового подключения к базе данных будет использоваться режим многопоточности "multi-thread". Это означает, что разные потоки могут одновременно использовать SQLite, если каждый поток использует отдельное подключение к базе данных.

SQLITE_OPEN_FULLMUTEX

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

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

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

Если третий параметр sqlite3_open_v2() не является одной из указанных выше обязательных комбинаций, возможно объединённых с другими флагами SQLITE_OPEN_*, поведение не определено. В исторических версиях SQLite лишние биты параметра flags в sqlite3_open_v2() молча игнорировались, однако в будущих версиях это поведение может измениться, поэтому приложениям не следует на него полагаться. В частности, обратите внимание, что флаг 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 включена, если в третьем аргументе sqlite3_open_v2() установлен флаг SQLITE_OPEN_URI, если она была включена глобально с помощью параметра SQLITE_CONFIG_URI метода sqlite3_config() или параметра компиляции SQLITE_USE_URI. По умолчанию интерпретация имени файла URI отключена, однако в будущих выпусках SQLite она может быть включена по умолчанию. Дополнительную информацию см. в разделе «Имена файлов URI».

Имена файлов URI разбираются в соответствии с RFC 3986. Если URI содержит компонент authority, он должен быть либо пустой строкой, либо строкой "localhost". Если компонент authority не является пустой строкой или строкой "localhost", вызывающей стороне возвращается ошибка. Компонент fragment URI, если он присутствует, игнорируется.

SQLite использует компонент path URI как имя файла на диске, содержащего базу данных. Если path начинается с символа '/', он интерпретируется как абсолютный путь. Если path не начинается с '/', то есть компонент authority в URI отсутствует, он интерпретируется как относительный путь. В Windows первый компонент абсолютного пути — это обозначение диска (например, "C:").

Компонент query URI может содержать параметры, интерпретируемые либо самой SQLite, либо пользовательской реализацией VFS. SQLite и встроенные в неё VFS интерпретируют следующие параметры query:

• vfs: Параметр "vfs" можно использовать, чтобы указать имя объекта VFS, предоставляющего интерфейс операционной системы для доступа к файлу базы данных на диске. Если этому параметру задана пустая строка, используется объект VFS по умолчанию. Указание неизвестного VFS приводит к ошибке. Если используется sqlite3_open_v2() и параметр vfs присутствует, указанный в параметре VFS имеет приоритет над значением, переданным четвёртым параметром sqlite3_open_v2().

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

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

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

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

Указание неизвестного параметра в компоненте query URI не является ошибкой. Будущие версии SQLite могут распознавать дополнительные параметры query. Дополнительную информацию см. в разделе «Параметры query, имеющие специальное значение для 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" не является допустимым значением компонента authority.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	Только для Windows: открыть файл "data.db" на рабочем столе пользователя fred на диске C:. Обратите внимание, что экранирование %20 в этом примере не является строго обязательным: пробелы можно использовать в именах файлов URI напрямую.
file:data.db?mode=ro&cache=private	Открыть файл "data.db" в текущем каталоге только для чтения. Независимо от того, включён ли по умолчанию режим общего кэша, использовать частный кэш.
file:/home/fred/data.db?vfs=unix-dotfile	Открыть файл "/home/fred/data.db". Использовать специальный VFS "unix-dotfile", который использует файлы с точкой вместо рекомендательной блокировки posix.
file:data.db?mode=readonly	Ошибка. "readonly" не является допустимым значением параметра "mode". Вместо него используйте "ro": "file:data.db?mode=ro".

В компонентах path и query URI поддерживаются шестнадцатеричные escape-последовательности URI (%HH). Шестнадцатеричная escape-последовательность состоит из знака процента — "%" — за которым следуют ровно две шестнадцатеричные цифры, задающие значение октета. Перед интерпретацией компонентов path и query имени файла URI они кодируются в UTF-8, а каждая шестнадцатеричная escape-последовательность заменяется одним байтом, содержащим соответствующий октет. Если в результате этого процесса получается некорректная кодировка UTF-8, поведение не определено.

Примечание для пользователей Windows: Для аргумента filename в sqlite3_open() и sqlite3_open_v2() необходимо использовать кодировку UTF-8, а не текущую кодовую страницу. Имена файлов, содержащие символы других языков, перед передачей в sqlite3_open() или sqlite3_open_v2() необходимо преобразовать в UTF-8.

Примечание для пользователей Windows Runtime: Перед вызовом sqlite3_open() или sqlite3_open_v2() необходимо задать временный каталог. В противном случае могут не работать различные функции, которым требуются временные файлы.

См. также: sqlite3_temp_directory

Хук предварительного обновления.

#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
void *sqlite3_preupdate_hook(
  sqlite3 *db,
  void(*xPreUpdate)(
    void *pCtx,                   /* Copy of third arg to preupdate_hook() */
    sqlite3 *db,                  /* Database handle */
    int op,                       /* SQLITE_UPDATE, DELETE or INSERT */
    char const *zDb,              /* Database name */
    char const *zName,            /* Table name */
    sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */
    sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */
  ),
  void*
);
int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_count(sqlite3 *);
int sqlite3_preupdate_depth(sqlite3 *);
int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_blobwrite(sqlite3 *);
#endif

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

Интерфейс sqlite3_preupdate_hook() регистрирует функцию обратного вызова, которая вызывается перед каждой операцией INSERT, UPDATE и DELETE над таблицей базы данных. Для одного подключения к базе данных одновременно можно зарегистрировать не более одного хука предварительного обновления; каждый вызов sqlite3_preupdate_hook() заменяет предыдущую настройку. Хук предварительного обновления отключается вызовом sqlite3_preupdate_hook() с указателем NULL в качестве второго параметра. Третий параметр sqlite3_preupdate_hook() передаётся в качестве первого параметра функциям обратного вызова.

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

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

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

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

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

Интерфейс sqlite3_preupdate_count(D) возвращает количество столбцов в добавляемой, обновляемой или удаляемой строке.

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

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

Устаревшие функции трассировки и профилирования

void *sqlite3_trace(sqlite3*,
   void(*xTrace)(void*,const char*), void*);
void *sqlite3_profile(sqlite3*,
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);

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

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

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

Параметр компиляции 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 *z, sqlite3_uint64 n,
                           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().

Эти функции очень похожи на семейство функций привязки параметров, используемых для привязки значений к параметрам SQL в подготовленных инструкциях. Дополнительную информацию см. в документации по параметрам 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. Строку из sqlite3_result_error16() SQLite интерпретирует как 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(C,Z,N,D,E) задаёт возвращаемое значение определённой приложением функции как текстовую строку в кодировке, указанной параметром E, который должен иметь одно из значений SQLITE_UTF8, SQLITE_UTF8_ZT, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE. Специальное значение SQLITE_UTF8_ZT означает, что результирующий текст представлен в UTF-8 и завершается нулевым символом. Иными словами, SQLITE_UTF8_ZT означает, что массив Z содержит не менее N+1 байта и что Z[N] равен нулю. SQLite получает текстовый результат приложения из второго параметра интерфейсов sqlite3_result_text*. Если третий параметр любого интерфейса sqlite3_result_text*, кроме sqlite3_result_text64(), отрицательный, SQLite самостоятельно вычисляет длину строки, находя в втором параметре первый нулевой символ. Если третий параметр интерфейсов sqlite3_result_text* неотрицательный, в качестве результата определённой приложением функции используется указанное количество байтов (не символов) текста, на который указывает второй параметр. Если третий параметр неотрицательный, он должен задавать смещение в байтах внутри строки, где находился бы терминатор NUL, если бы строка завершалась нулём. Если в строке встречаются нулевые символы со смещением в байтах меньше значения третьего параметра, результирующая строка будет содержать встроенные нулевые символы, а поведение выражений, работающих со строками, содержащими встроенные нулевые символы, не определено. Если четвёртый параметр интерфейсов 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, эти символы могут быть преобразованы в символ замены Unicode U+FFFD.

Интерфейс sqlite3_result_value() задаёт результат определённой приложением функции как копию объекта незащищённый sqlite3_value, указанного вторым параметром. Интерфейс sqlite3_result_value() создаёт копию sqlite3_value, поэтому указанный в параметре объект sqlite3_value можно изменить или освободить после возврата sqlite3_result_value() без последствий. Объект защищённый sqlite3_value всегда можно использовать там, где требуется объект незащищённый sqlite3_value, поэтому с этим интерфейсом можно использовать объект sqlite3_value любого из этих типов.

Интерфейс sqlite3_result_pointer(C,P,T,D) задаёт результат как значение SQL NULL, как и sqlite3_result_null(C), но дополнительно связывает с этим значением NULL указатель P или тип T языка-хоста, чтобы этот указатель можно было получить в определённой приложением SQL-функции с помощью sqlite3_value_pointer(). Если параметр D не равен NULL, он является указателем на деструктор параметра P. Когда SQLite завершит работу с P, SQLite вызовет D, передав P как единственный аргумент. Параметр T должен быть статической строкой, предпочтительно строковым литералом. Подпрограмма sqlite3_result_pointer() является частью интерфейса передачи указателей, добавленного в SQLite 3.20.0.

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

Состояние SQLite во время выполнения

int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
int sqlite3_status64(
  int op,
  sqlite3_int64 *pCurrent,
  sqlite3_int64 *pHighwater,
  int resetFlag
);

Эти интерфейсы используются для получения сведений о состоянии SQLite во время выполнения, в том числе о производительности, и при необходимости для сброса различных максимальных значений. Первый аргумент — целочисленный код измеряемого параметра. Распознаваемые целочисленные коды имеют вид SQLITE_STATUS_.... Текущее значение параметра записывается в *pCurrent. Наибольшее зарегистрированное значение записывается в *pHighwater. Если resetFlag имеет значение true, наибольшее зарегистрированное значение сбрасывается после записи в *pHighwater. Для некоторых параметров наибольшее значение не регистрируется. Для таких параметров в *pHighwater ничего не записывается, а resetFlag игнорируется. Для других параметров регистрируется только максимальное значение, но не текущее. Для этих параметров в *pCurrent ничего не записывается.

Подпрограммы sqlite3_status() и sqlite3_status64() при успешном выполнении возвращают SQLITE_OK, а при ошибке — ненулевой код ошибки.

Если текущее значение или максимальное значение слишком велико, чтобы быть представимым 32-разрядным целым числом, значения, возвращаемые sqlite3_status(), не определены.

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

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

int sqlite3_stmt_scanstatus(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  void *pOut                /* Result written here */
);
int sqlite3_stmt_scanstatus_v2(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  int flags,                /* Mask of flags defined below */
  void *pOut                /* Result written here */
);

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

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

Параметр "iScanStatusOp" определяет, какие сведения о состоянии нужно вернуть. "iScanStatusOp" должен быть одним из параметров scanstatus, иначе поведение этого интерфейса не определено. Запрошенное измерение записывается в переменную, на которую указывает параметр "pOut".

Параметру "flags" необходимо передать маску флагов. В настоящее время определён только один флаг — SQLITE_SCANSTAT_COMPLEX. Если указан SQLITE_SCANSTAT_COMPLEX, сведения о состоянии доступны для всех элементов плана запроса, отображаемых в выводе "EXPLAIN QUERY PLAN". Если SQLITE_SCANSTAT_COMPLEX не указан, доступны только элементы плана запроса, соответствующие циклам запроса (элементы "SCAN..." и "SEARCH..." в выводе EXPLAIN QUERY PLAN). Вызов API sqlite3_stmt_scanstatus() эквивалентен вызову sqlite3_stmt_scanstatus_v2() с нулевым параметром flags.

Параметр "idx" задаёт конкретный элемент запроса, для которого нужно получить статистику. Нумерация элементов запроса начинается с нуля. Значение -1 может использоваться для получения статистики по всему запросу. Если idx выходит за допустимые пределы — меньше -1 или больше либо равно общему количеству элементов запроса, использованных для выполнения оператора, — возвращается ненулевое значение, а переменная, на которую указывает pOut, не изменяется.

См. также: sqlite3_stmt_scanstatus_reset() и столбцы nexec и ncycle виртуальной таблицы байткода.

Добавление содержимого в динамическую строку

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*);
void sqlite3_str_truncate(sqlite3_str*,int N);

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

Интерфейсы sqlite3_str_appendf(X,F,...) и sqlite3_str_vappendf(X,F,V) используют встроенные средства SQLite для форматированного вывода printf, чтобы добавить форматированный текст в конец объекта 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_truncate(X,N) изменяет длину создаваемой строки так, чтобы она составляла не более N байт. Эта подпрограмма ничего не делает, если N отрицательно или если длина строки уже не превышает N байт.

Эти методы не возвращают код результата. Если происходит ошибка, сведения о ней сохраняются в объекте 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_MAX_LENGTH — SQLITE_TOOBIG, а если ошибок не было — SQLITE_OK.

Метод sqlite3_str_length(X) возвращает текущую длину в байтах создаваемой динамической строки в объекте sqlite3_str X. Возвращаемая методом sqlite3_str_length(X) длина не включает байт нулевого терминатора.

Метод sqlite3_str_value(X) возвращает указатель на текущее содержимое создаваемой динамической строки в X. Возвращаемое методом sqlite3_str_value(X) значение управляется объектом sqlite3_str X и может быть освобождено или изменено любым последующим методом для того же объекта sqlite3_str. Приложения не должны использовать указатель, возвращённый sqlite3_str_value(X), после любого последующего вызова метода для того же объекта. Приложения могут изменять содержимое строки, возвращённой sqlite3_str_value(X), если не записывают байты за пределами диапазона от 0 до sqlite3_str_length(X) и не читают и не записывают байты после последующего вызова любого метода sqlite3_str.

Завершение динамической строки

char *sqlite3_str_finish(sqlite3_str*);
void sqlite3_str_free(sqlite3_str*);

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

Интерфейс sqlite3_str_free(X) уничтожает объект sqlite3_str X и содержащуюся в нём строку. Вызов sqlite3_str_free(X) эквивалентен вызову sqlite3_free(sqlite3_str_finish(X)).

Сравнение строк

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, если он существует, или нулевой указатель, если 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 или его значение не соответствует ни одному из перечисленных вариантов, 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 или нулевой указатель, если N меньше нуля или больше количества параметров запроса минус 1. Значение N отсчитывается от нуля: чтобы получить имя первого параметра запроса, укажите N равным 0, второго — 1 и так далее.

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

Начиная с версии 3.31.0 SQLite (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 

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

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

Эти подпрограммы работают только с объектами защищённый sqlite3_value. Любая попытка использовать их с объектом незащищённый sqlite3_value небезопасна в многопоточной среде.

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

Интерфейс sqlite3_value_text16() извлекает строку UTF-16 с собственным для компьютера порядком байтов. Интерфейсы sqlite3_value_text16be() и sqlite3_value_text16le() извлекают строки UTF-16 соответственно с порядком байтов от старшего к младшему и от младшего к старшему.

Если объект sqlite3_value V был инициализирован с помощью sqlite3_bind_pointer(S,I,P,X,D) или sqlite3_result_pointer(C,P,X,D), а строки X и Y совпадают согласно strcmp(X,Y), то sqlite3_value_pointer(V,Y) вернёт указатель P. В противном случае sqlite3_value_pointer(V,Y) возвращает NULL. Подпрограмма sqlite3_bind_pointer() является частью интерфейса передачи указателей, добавленного в SQLite 3.20.0.

Интерфейс sqlite3_value_type(V) возвращает код типа данных исходного типа данных объекта sqlite3_value V. Возвращаемое значение — одно из SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB или SQLITE_NULL. Другие интерфейсы могут изменить тип данных объекта sqlite3_value. Например, если исходный тип данных — SQLITE_INTEGER и для извлечения текстового значения этого целого числа вызывается sqlite3_value_text(V), последующие вызовы sqlite3_value_type(V) могут вернуть SQLITE_TEXT. Не определено, происходит ли постоянное внутреннее преобразование типа данных; это поведение может меняться от одной версии SQLite к другой.

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

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

При условии, что входной параметр корректен, эти подпрограммы могут завершиться с ошибкой только в случае нехватки памяти при преобразовании UTF8→UTF16 или UTF16→UTF8. Если возникает ошибка нехватки памяти, возвращаемое этими подпрограммами значение совпадает с тем, которое было бы возвращено, если бы столбец содержал SQL NULL. Если входной sqlite3_value не был получен с помощью sqlite3_value_dup(), после извлечения значения корректный возврат SQL NULL можно отличить от ошибки нехватки памяти: сразу после получения подозрительного возвращаемого значения и до вызова любого другого интерфейса SQLite для того же соединения с базой данных вызовите sqlite3_errcode(). Если входной sqlite3_value был получен с помощью sqlite3_value_dup(), он не связан с соединением с базой данных, поэтому sqlite3_errcode() не сработает. В этом случае единственный способ отличить нехватку памяти от настоящего SQL NULL — вызвать sqlite3_value_type() для входного значения и проверить, равно ли оно NULL, прежде чем пытаться извлечь значение.

Копирование и освобождение значений SQL

sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
void sqlite3_value_free(sqlite3_value*);

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

Интерфейс sqlite3_vfs_find() возвращает указатель на VFS по её имени. Имена чувствительны к регистру. Имена представляют собой строки UTF-8 с нулевым терминатором. Если соответствие не найдено, возвращается нулевой указатель. Если 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_DONE ){
     // 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 — в зависимости от значения параметра type. Параметр zValue должен быть равен NULL, чтобы предыдущее значение было освобождено с помощью sqlite3_free; значение, отличное от NULL, будет скопировано в память, полученную с помощью sqlite3_malloc, прежде чем использоваться. Интерфейс sqlite3_win32_set_directory возвращает SQLITE_OK при успешном выполнении, SQLITE_ERROR, если тип не поддерживается, или SQLITE_NOMEM, если не удалось выделить память. Значение переменной sqlite3_data_directory предназначено для замены текущего каталога на под-платформах Win32, где это понятие отсутствует, например в WinRT и UWP. Интерфейсы sqlite3_win32_set_directory8 и sqlite3_win32_set_directory16 работают точно так же, как интерфейс sqlite3_win32_set_directory, за исключением того, что строковый параметр должен иметь кодировку UTF-8 или UTF-16 соответственно.

Привязка значений к подготовленным операторам

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
                        void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
                         void(*)(void*), unsigned char encoding);
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);

В тексте SQL-оператора, передаваемом в sqlite3_prepare_v2() и его варианты, литералы могут быть заменены параметром, соответствующим одному из следующих шаблонов:

• ?
• ?NNN
• :VVV
• @VVV
• $VVV

В приведенных выше шаблонах NNN обозначает целочисленный литерал, а VVV — буквенно-цифровой идентификатор. Значения этих параметров (также называемых «именами параметров хоста» или «параметрами SQL») можно задать с помощью определенных здесь процедур sqlite3_bind_*().

Первый аргумент процедур sqlite3_bind_*() всегда является указателем на объект sqlite3_stmt, возвращенный sqlite3_prepare_v2() или его вариантами.

Второй аргумент — это индекс задаваемого параметра SQL. Крайний левый параметр SQL имеет индекс 1. Если один и тот же именованный параметр SQL используется несколько раз, его второе и последующие вхождения имеют тот же индекс, что и первое. При необходимости индекс именованных параметров можно получить с помощью API sqlite3_bind_parameter_index(). Индекс параметров «?NNN» равен значению NNN. Значение NNN должно находиться в диапазоне от 1 до значения параметра SQLITE_LIMIT_VARIABLE_NUMBER функции sqlite3_limit() (по умолчанию: 32766).

Третий аргумент — это значение, привязываемое к параметру. Если третий параметр sqlite3_bind_text(), sqlite3_bind_text16() или sqlite3_bind_blob() является указателем NULL, четвертый параметр игнорируется, и в результате выполняется то же, что и при вызове sqlite3_bind_null(). Если третий параметр sqlite3_bind_text() не равен NULL, он должен быть указателем на корректный текст UTF8. Если третий параметр sqlite3_bind_text16() не равен NULL, он должен быть указателем на корректный текст UTF16. Если третий параметр sqlite3_bind_text64() не равен NULL, он должен быть указателем на корректную строку Unicode в кодировке UTF8, если шестой параметр равен SQLITE_UTF8 или SQLITE_UTF8_ZT, либо в кодировке UTF16 в противном случае.

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

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

Пятый аргумент интерфейсов привязки BLOB и строк управляет временем жизни объекта, на который указывает третий параметр, или сообщает о нем. Существуют три варианта: (1) Можно передать деструктор для освобождения BLOB-объекта или строки после того, как SQLite завершит работу с ними. Он будет вызван для освобождения BLOB-объекта или строки, даже если вызов API привязки завершится неудачно, за исключением случаев, когда третий параметр является указателем NULL или четвертый параметр отрицателен. (2) Можно передать специальную константу SQLITE_STATIC, чтобы указать, что приложение отвечает за освобождение объекта. В этом случае объект и переданный указатель на него должны оставаться действительными до завершения подготовки оператора или до привязки к тому же параметру SQL другого значения — в зависимости от того, что произойдет раньше. (3) Можно передать константу SQLITE_TRANSIENT, чтобы указать, что объект нужно скопировать до возврата из sqlite3_bind_*(). Объект и указатель на него должны оставаться действительными до этого момента. Затем SQLite будет управлять временем жизни своей частной копии.

Шестой аргумент (аргумент E) функции sqlite3_bind_text64(S,K,Z,N,D,E) должен иметь одно из значений SQLITE_UTF8, SQLITE_UTF8_ZT, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE, указывающих кодировку текста в третьем параметре Z. Специальное значение SQLITE_UTF8_ZT означает, что строковый аргумент закодирован в UTF-8 и завершается нулевым байтом. Иными словами, SQLITE_UTF8_ZT означает, что массив Z выделен как минимум для N+1 байта, а байт Z[N] равен нулю. Если аргумент E функции sqlite3_bind_text64(S,K,Z,N,D,E) не имеет одного из допустимых значений, перечисленных выше, или если кодировка текста отличается от кодировки, указанной шестым параметром, поведение не определено.

Процедура sqlite3_bind_zeroblob() привязывает BLOB-объект длины N, заполненный нулями. Во время обработки zeroblob использует фиксированный объем памяти (только целое число для хранения его размера). Zeroblob предназначены для использования в качестве заполнителей для BLOB-объектов, содержимое которых позднее записывается с помощью процедур инкрементного ввода-вывода BLOB. Отрицательное значение для zeroblob приводит к созданию BLOB-объекта нулевой длины.

Процедура sqlite3_bind_pointer(S,I,P,T,D) устанавливает для I-го параметра в подготовленном операторе S значение SQL NULL, одновременно связывая его с указателем P типа T. D — это указатель NULL или указатель на функцию-деструктор для P. Когда SQLite завершит работу с P, она вызовет деструктор D с аргументом P, даже если вызов sqlite3_bind_pointer() завершится неудачно. Из-за исторической особенности проектирования результат не определен, если D равен SQLITE_TRANSIENT. Параметр 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-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. Если схема базы данных изменится, sqlite3_step() автоматически скомпилирует оператор SQL заново и попытается выполнить его, вместо того чтобы вернуть SQLITE_SCHEMA, как это происходило ранее. Прежде чем 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, то подготовленный оператор создается таким образом, чтобы вместо значения столбца таблицы, которое было бы прочитано при возврате SQLITE_OK, подставлялось значение NULL. Возврат SQLITE_IGNORE можно использовать, чтобы запретить ненадежному пользователю доступ к отдельным столбцам таблицы. Если таблица указана в SELECT, но из нее не извлекаются значения столбцов (например, в запросе «SELECT count(*) FROM tab»), функция обратного вызова авторизации SQLITE_READ вызывается один раз для этой таблицы с пустым именем столбца. Если код действия равен SQLITE_DELETE, а функция обратного вызова возвращает SQLITE_IGNORE, операция DELETE выполняется, но оптимизация усечения отключается, и все строки удаляются по отдельности.

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

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

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

Если функция обратного вызова busy равна NULL, при обнаружении блокировки немедленно возвращается SQLITE_BUSY. Если функция обратного вызова busy не равна NULL, она может быть вызвана с двумя аргументами.

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

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

По умолчанию функция обратного вызова busy равна NULL.

Для каждого подключения к базе данных может быть определен только один обработчик busy. Установка нового обработчика очищает ранее установленный. Обратите внимание, что вызов sqlite3_busy_timeout() или выполнение PRAGMA busy_timeout=N изменяет обработчик busy и тем самым очищает ранее установленный обработчик.

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

Обработчик busy не должен закрывать подключение к базе данных или подготовленный оператор, вызвавший обработчик busy.

Значения результата запроса

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

Если результатом является 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	CAST в INTEGER
FLOAT	TEXT	Текстовое представление числа с плавающей точкой в ASCII
FLOAT	BLOB	CAST в BLOB
TEXT	INTEGER	CAST в INTEGER
TEXT	FLOAT	CAST в REAL
TEXT	BLOB	Без изменений
BLOB	INTEGER	CAST в INTEGER
BLOB	FLOAT	CAST в REAL
BLOB	TEXT	CAST в TEXT с добавлением нулевого завершающего символа

Обратите внимание: при выполнении преобразований типов указатели, возвращённые предыдущими вызовами sqlite3_column_blob(), sqlite3_column_text() и/или sqlite3_column_text16(), могут стать недействительными. Преобразования типов и аннулирование указателей могут происходить в следующих случаях:

• Исходное содержимое имеет тип BLOB, и вызывается sqlite3_column_text() или sqlite3_column_text16(). Возможно, потребуется добавить к строке нулевой завершающий символ.
• Исходное содержимое — текст в кодировке UTF-8, и вызывается sqlite3_column_bytes16() или sqlite3_column_text16(). Содержимое необходимо преобразовать в UTF-16.
• Исходное содержимое — текст в кодировке UTF-16, и вызывается sqlite3_column_bytes() или sqlite3_column_text(). Содержимое необходимо преобразовать в UTF-8.

Преобразования между UTF-16be и UTF-16le всегда выполняются на месте и не делают ранее полученный указатель недействительным, однако содержимое буфера, на который он указывает, будет изменено. Другие виды преобразований выполняются на месте, когда это возможно; если же это невозможно, ранее полученные указатели становятся недействительными.

Наиболее безопасно вызывать эти процедуры одним из следующих способов:

• sqlite3_column_text() с последующим sqlite3_column_bytes()
• sqlite3_column_blob() с последующим sqlite3_column_bytes()
• sqlite3_column_text16() с последующим sqlite3_column_bytes16()

Иными словами, сначала следует вызвать sqlite3_column_text(), sqlite3_column_blob() или sqlite3_column_text16(), чтобы принудительно преобразовать результат в нужный формат, а затем вызвать sqlite3_column_bytes() или sqlite3_column_bytes16(), чтобы определить размер результата. Не смешивайте вызовы sqlite3_column_text() или sqlite3_column_blob() с вызовами sqlite3_column_bytes16() и не смешивайте вызовы sqlite3_column_text16() с вызовами sqlite3_column_bytes().

Возвращённые указатели действительны до преобразования типа, описанного выше, либо до вызова sqlite3_step(), sqlite3_reset() или sqlite3_finalize(). Память, используемая для хранения строк и BLOB, освобождается автоматически. Не передавайте указатели, возвращённые sqlite3_column_blob(), sqlite3_column_text() и т. д., в sqlite3_free().

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

• sqlite3_column_blob()
• sqlite3_column_text()
• sqlite3_column_text16()
• sqlite3_column_bytes()
• sqlite3_column_bytes16()

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

Низкоуровневое управление файлами баз данных

int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

Интерфейс sqlite3_file_control() напрямую вызывает метод xFileControl объекта sqlite3_io_methods, связанного с конкретной базой данных, указанной вторым аргументом. Имя основной базы данных — "main", временной базы данных — "temp", а для баз данных, добавленных с помощью SQL-команды ATTACH, используется имя, указанное после ключевого слова AS. Вместо "main" для ссылки на файл основной базы данных можно использовать указатель NULL. Третий и четвёртый параметры этой процедуры напрямую передаются как второй и третий параметры метода xFileControl. Возвращаемое значение метода xFileControl становится возвращаемым значением этой процедуры.

Некоторые коды операций для sqlite3_file_control() обрабатываются непосредственно ядром SQLite и никогда не вызывают метод sqlite3_io_methods.xFileControl. Значение SQLITE_FCNTL_FILE_POINTER параметра op приводит к записи указателя на базовый объект sqlite3_file в область памяти, на которую указывает 4-й параметр. Код SQLITE_FCNTL_JOURNAL_POINTER работает аналогично, но возвращает объект sqlite3_file, связанный с файлом журнала, а не с основной базой данных. Код SQLITE_FCNTL_VFS_POINTER возвращает указатель на базовый объект sqlite3_vfs для файла. Код SQLITE_FCNTL_DATA_VERSION возвращает счётчик версии данных из pager.

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