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