Компиляция SQL-запроса

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v3(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v3(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

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

Рекомендуемая процедура — sqlite3_prepare_v2(). Интерфейс sqlite3_prepare() является устаревшим и следует избегать его использования. sqlite3_prepare_v3() имеет дополнительный параметр «prepFlags», используемый для специальных целей.

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

Первый аргумент, «db», представляет собой соединение с базой данных, полученное в результате успешного предыдущего вызова sqlite3_open(), sqlite3_open_v2() или sqlite3_open16(). Соединение с базой данных не должно быть закрыто.

Второй аргумент, «zSql», представляет собой запрос, который необходимо скомпилировать, закодированный в UTF-8 или UTF-16. Интерфейсы sqlite3_prepare(), sqlite3_prepare_v2() и sqlite3_prepare_v3() используют UTF-8, а sqlite3_prepare16(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() используют UTF-16.

Если аргумент nByte отрицательный, то zSql считывается до первой нулевой терминирующей последовательности. Если nByte положительный, то это максимальное количество считанных байтов из zSql. При положительном nByte zSql считывается до первой нулевой терминирующей последовательности или до тех пор, пока не будет прочитано nByte байтов, в зависимости от того, что произойдёт раньше. Если nByte равен нулю, то подготовленный запрос не генерируется. Если вызывающая процедура знает, что предоставленная строка завершается нулём, то существует небольшое преимущество производительности при передаче параметра nByte, являющегося количеством байтов в входной строке, включая нулевой терминатор. Обратите внимание, что nByte измеряет длину ввода в байтах, а не в символах, даже для интерфейсов UTF-16.

Если pzTail не равен NULL, то *pzTail устанавливается для указания на первый байт после конца первого SQL-запроса в zSql. Эти процедуры компилируют только первый запрос в zSql, поэтому *pzTail остаётся указывающим на то, что осталось не скомпилированным.

*ppStmt остаётся указывающим на скомпилированный подготовленный запрос, который можно выполнить с помощью sqlite3_step(). При ошибке *ppStmt устанавливается в NULL. Если входной текст не содержит SQL-кода (если вход — пустая строка или комментарий), *ppStmt устанавливается в NULL. Вызывающая процедура отвечает за удаление скомпилированного SQL-запроса с помощью sqlite3_finalize() после его использования. ppStmt не может быть NULL.

При успешном выполнении семейство процедур sqlite3_prepare() возвращает SQLITE_OK; в противном случае возвращается код ошибки.

Интерфейсы sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() рекомендуются для всех новых программ. Устаревшие интерфейсы (sqlite3_prepare() и sqlite3_prepare16()) сохраняются для обратной совместимости, но их использование не рекомендуется. В интерфейсах «vX» подготовленный запрос, который возвращается (объект sqlite3_stmt), содержит копию исходного SQL-текста. Это приводит к тому, что интерфейс sqlite3_step() ведёт себя по-другому в трёх аспектах:

1. Если схема базы данных изменяется, вместо возвращения SQLITE_SCHEMA, как это всегда происходило раньше, sqlite3_step() будет автоматически перекомпилировать SQL-запрос и попытаться выполнить его снова. Будет предпринято до SQLITE_MAX_SCHEMA_RETRY попыток, прежде чем sqlite3_step() откажется и вернёт ошибку.
2. При возникновении ошибки sqlite3_step() вернёт один из подробных кодов ошибок или расширенных кодов ошибок. Раньше sqlite3_step() возвращал только общий код SQLITE_ERROR, и приложение должно было сделать второй вызов sqlite3_reset(), чтобы найти причину проблемы. С интерфейсами «v2» подготовка сразу возвращает причину ошибки.
3. Если конкретное значение, привязанное к параметру хоста в предложении WHERE, может повлиять на выбор плана запроса для запроса, запрос будет автоматически перекомпилирован, как если бы произошли изменения в схеме, при первом вызове sqlite3_step() после любого изменения связей этого параметра. Конкретное значение параметра WHERE может повлиять на выбор плана запроса, если параметр является левой частью оператора LIKE или GLOB, или если параметр сравнивается с индексированным столбцом, и опция компиляции SQLITE_ENABLE_STAT4 включена.

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

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