Программные приложения должны использовать этот общий план для взаимодействия с MySQL с помощью библиотеки клиента:

Целью вызова mysql_library_init() и mysql_library_end() является предоставление надлежащей инициализации и завершения работы библиотеки клиента MySQL. Для приложений, связанных с библиотекой клиента, они обеспечивают улучшенное управление памятью. Если вы не вызываете mysql_library_end(), блок памяти остается выделенным. (Это не увеличивает объем памяти, используемой приложением, но некоторые детекторы утечек памяти могут о них сообщить.)

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

Чтобы подключиться к серверу, вызовите mysql_init() для инициализации обработчика соединения, а затем вызовите функцию установления соединения, такую как mysql_real_connect() с этим обработчиком (наряду с другой информацией, такой как имя хоста, имя пользователя и пароль). Когда вы закончите с подключением, вызовите mysql_close() для его завершения. Не используйте обработчик после его закрытия.

После подключения mysql_real_connect() устанавливает флаг reconnect (часть структуры MYSQL) в значение 0. Вы можете использовать опцию MYSQL_OPT_RECONNECT (устаревшая начиная с MySQL 8.0.34) для mysql_options(), чтобы управлять поведением повторного подключения. Установка флага в 1 заставляет клиент пытаться повторно подключиться к серверу перед отказом, если операция не может быть выполнена из-за потери соединения.

Пока соединение активно, клиент может отправлять SQL-запросы на сервер с помощью mysql_real_query() или mysql_query(). Разница между ними заключается в том, что mysql_query() ожидает, что запрос будет задан в виде строки с завершающим нулем, в то время как mysql_real_query() ожидает строку с указанием длины. Если строка содержит двоичные данные (включая нулевые байты), вы должны использовать mysql_real_query().

Для каждого не- запроса (например, , , ), вы можете узнать, сколько строк было изменено (затронуто), вызвав mysql_affected_rows().

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

Существует два способа, с помощью которых клиент может обрабатывать наборы результатов. Один способ - получить весь набор результатов сразу, вызвав mysql_store_result(). Эта функция получает от сервера все строки, возвращенные запросом, и сохраняет их в клиенте. Второй способ - инициировать получение набора результатов строка за строкой, вызвав mysql_use_result(). Эта функция инициализирует процесс получения, но фактически не получает никакие строки от сервера.

В обоих случаях вы получаете доступ к строкам, вызывая mysql_fetch_row(). С помощью mysql_store_result(), mysql_fetch_row() получает доступ к строкам, которые ранее были получены с сервера. С помощью mysql_use_result(), mysql_fetch_row() фактически получает строку с сервера. Информацию о размере данных в каждой строке можно получить, вызвав mysql_fetch_lengths().

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

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

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

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

API позволяет клиентам должным образом реагировать на операторы (получение строк только при необходимости), не зная, является ли оператор . Вы можете сделать это, вызвав mysql_store_result() после каждого вызова mysql_real_query() (или mysql_query()). Если вызов набора результатов выполняется успешно, оператор был и вы можете прочитать строки. Если вызов набора результатов завершился неудачей, вызовите mysql_field_count(), чтобы определить, ожидался ли результат. Если mysql_field_count() возвращает ноль, оператор не вернул данных (указывая, что это был , , , и так далее), и не ожидалось, что он вернет строки. Если mysql_field_count() не равно нулю, оператор должен был вернуть строки, но не вернул. Это указывает на то, что оператор был и завершился неудачей. См. описание mysql_field_count() для примера того, как это можно сделать.

Обе функции mysql_store_result() и mysql_use_result() позволяют получить информацию о полях, составляющих результат запроса (количество полей, их имена и типы и так далее). Вы можете последовательно получать информацию о полях в строке, вызывая функцию mysql_fetch_field() многократно или по номеру поля в строке, вызывая mysql_fetch_field_direct(). Текущую позицию курсора поля можно изменить, вызвав функцию mysql_field_seek(). Установка курсора поля влияет на последующие вызовы функции mysql_fetch_field(). Также вы можете получить информацию обо всех полях сразу, вызвав mysql_fetch_fields().

Для обнаружения и сообщения об ошибках MySQL предоставляет доступ к информации об ошибках с помощью функций mysql_errno() и mysql_error(). Они возвращают код ошибки или сообщение об ошибке для последней вызванной функции, которая может завершиться успешно или неуспешно, что позволяет определить, когда произошла ошибка и в чём она заключается.