6.1 Overview of the C API Prepared Statement Interface — MySQL Connectors 1.0

6.1 Обзор интерфейса подготовленных запросов C API

Для подготовки и выполнения запроса приложение выполняет следующие шаги:

Создайте обработчик подготовленного запроса с помощью mysql_stmt_init(). Чтобы подготовить запрос на сервере, вызовите mysql_stmt_prepare() и передайте ему строку с SQL-запросом.
Установите значения параметров с помощью mysql_stmt_bind_param() или mysql_stmt_bind_named_param(). Все параметры должны быть установлены. В противном случае выполнение запроса вернёт ошибку или даст непредсказуемые результаты.

Если есть большие значения текстовых или двоичных данных, которые необходимо отправить, вы можете отправлять их частями на сервер с помощью mysql_stmt_send_long_data().
Вызовите mysql_stmt_execute() для выполнения запроса.
Если запрос является запросом, возвращающим набор результатов, или любым другим запросом, который возвращает набор результатов, вызовите mysql_stmt_result_metadata(), если требуется получить метаданные набора результатов. Эти метаданные сами по себе представляют собой MYSQL_RES набор результатов, хотя и отдельный от того, который содержит строки, возвращаемые запросом. Метаданные набора результатов указывают количество столбцов в результате и содержат информацию о каждом из них.
Если запрос возвращает набор результатов, привяжите буферы данных для извлечения значений строк, вызвав mysql_stmt_bind_result().
Извлекайте данные в буферы строка за строкой, вызывая mysql_stmt_fetch() до тех пор, пока не будут найдены все строки.
Повторяйте шаги 3–6 по мере необходимости. Вы можете повторить mysql_stmt_execute() для повторного выполнения запроса, изменив значения параметров в соответствующих буферах, предоставленных через mysql_stmt_bind_param() или mysql_stmt_bind_named_param().
После завершения выполнения запроса закройте обработчик запроса с помощью mysql_stmt_close(), чтобы освободить все связанные с ним ресурсы. В этот момент обработчик становится недействительным и больше не должен использоваться.
Если вы получили метаданные набора результатов запроса, вызвав mysql_stmt_result_metadata(), вы также должны освободить метаданные с помощью mysql_free_result().

При вызове mysql_stmt_prepare() протокол MySQL клиент/сервер выполняет следующие действия:

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

При вызове mysql_stmt_execute() протокол MySQL клиент/сервер выполняет следующие действия:

Клиент использует обработчик запроса и отправляет данные параметров на сервер.
Сервер идентифицирует запрос с помощью предоставленного клиентом идентификатора, заменяет маркеры параметров новыми предоставленными данными и выполняет запрос. Если запрос возвращает набор результатов, сервер отправляет данные клиенту. В противном случае он отправляет статус «ОК» и количество изменённых, удалённых или вставленных строк.

При вызове mysql_stmt_fetch() протокол MySQL клиент/сервер выполняет следующие действия:

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

В случае возникновения ошибки можно получить номер ошибки запроса, сообщение об ошибке и код SQLSTATE с помощью mysql_stmt_errno(), mysql_stmt_error() и mysql_stmt_sqlstate() соответственно.

Ведение журнала подготовленных запросов

Для подготовленных запросов, выполняемых с помощью функций C API mysql_stmt_prepare() и mysql_stmt_execute(), сервер записывает Prepare и Execute строки в общий журнал запросов, чтобы вы могли отслеживать, когда запросы готовятся и выполняются.

Предположим, что вы готовите и выполняете запрос следующим образом:

Вызовите mysql_stmt_prepare() для подготовки строки запроса "SELECT ?".
Вызовите mysql_stmt_bind_param() или mysql_stmt_bind_named_param() для привязки значения 3 к параметру в подготовленном запросе.
Вызовите mysql_stmt_execute() для выполнения подготовленного запроса.

В результате предыдущих вызовов сервер запишет следующие строки в общий журнал запросов:

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

Каждая Prepare и Execute строка в журнале помечена идентификатором [N] подготовленного запроса, чтобы вы могли отслеживать, какой подготовленный запрос регистрируется. N — положительное целое число. Если одновременно активны несколько подготовленных запросов для клиента, N может быть больше 1. Каждая строка Execute отображает подготовленный запрос после подстановки значений данных для параметров ?.