mysqli::multi_query

mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Выполняет запросы к базе данных

Описание

Объектно-ориентированный стиль

public mysqli::multi_query(string $query): bool

Процедурный стиль

mysqli_multi_query(mysqli $mysql, string $query): bool

Функция отправляет одну или пакет SQL-инструкций, которые требуется выполнить на сервере баз данных. Инструкции перечисляют через точку с запятой.

Внимание

Предупреждение безопасности: SQL-инъекция

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

SQL-инструкции отправляются в одном сетевом запросе к базе данных и обрабатываются последовательно. Функция mysqli_multi_query() дожидается завершения обработки первой SQL-инструкции, а затем возвращает управление PHP. Тем временем MySQL-сервер продолжает асинхронно обрабатывать остальные инструкции и готовит результат для очередного извлечения PHP-функциями.

Пакетные запросы часто обрабатывают в цикле do-while. Соединение останется недоступным для выполнения других SQL-инструкций, пока MySQL не обработает, а PHP не извлечёт результаты пакета инструкций. Для перехода к следующему результату последовательности вызывают функцию mysqli_next_result(). Модуль mysqli заблокирует работу скрипта, если потребуется дождаться ответа MySQL-сервера о готовности следующего результата. Завершил ли сервер обработку инструкций и выдачу результатов, проверяют функцией mysqli_more_results().

Наборы результатов, которые возвращаются инструкциями наподобие SELECT, SHOW, DESCRIBE или EXPLAIN, извлекают функцией mysqli_use_result() или mysqli_store_result(). Из запросов, которые не возвращают набор результатов, этими же функциями получают информацию о количестве затронутых строк или другие метаданные.

Подсказка

Выполнение SQL-инструкций CALL при вызове хранимых процедур в ряде сценариев возвращает множественные наборы результатов. Наборы результатов из хранимых процедур с инструкциями SELECT возвращаются по мере выполнения инструкций в порядке определения внутри процедуры. В общем случае вызывающая сторона не знает, сколько наборов результатов вернёт процедура, и поэтому готовится получить множественные результаты. Конечный результат процедуры — статус, который не включает набор результатов. Статус указывает, выполнилась ли процедура успешно или возникла ошибка.

Список параметров

mysql: Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
query: Строка с SQL-инструкциями, которые требуется отправить в запросе и выполнить на сервере. Инструкции разделяются точкой с запятой.

Возвращаемые значения

Функция возвращает false, если выполнение первой SQL-инструкции завершилось ошибкой. Перед проверкой ошибок по остальным инструкциям сначала вызывают функцию mysqli_next_result().

Ошибки

Если уведомления об ошибках mysqli включены (MYSQLI_REPORT_ERROR) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим MYSQLI_REPORT_STRICT, вместо этого будет выброшено исключение mysqli_sql_exception.

Примеры

Пример #1 Пример выполнения пакета SQL-инструкций методом mysqli::multi_query()

Объектно-ориентированный стиль

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* Выполнение пакета SQL-инструкций в одном запросе */
$mysqli->multi_query($query);
do {
    /* Сохранение набора результатов в PHP */
    if ($result = $mysqli->store_result()) {
        while ($row = $result->fetch_row()) {
            printf("%s\n", $row[0]);
        }
    }
    /* Вывод разделителя */
    if ($mysqli->more_results()) {
        printf("-----------------\n");
    }
} while ($mysqli->next_result());

Процедурный стиль

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* Выполнение пакета SQL-инструкций в одном запросе */
mysqli_multi_query($link, $query);
do {
    /* Сохранение набора результатов в PHP */
    if ($result = mysqli_store_result($link)) {
        while ($row = mysqli_fetch_row($result)) {
            printf("%s\n", $row[0]);
        }
    }
    /* Вывод разделителя */
    if (mysqli_more_results($link)) {
        printf("-----------------\n");
    }
} while (mysqli_next_result($link));

Вывод приведённых примеров будет похож на:

my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer

Смотрите также

mysqli_query() - Выполняет запрос к базе данных
mysqli_use_result() - Готовит результирующий набор на сервере к использованию
mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
mysqli_next_result() - Подготовка следующего доступного результирующего набора из multi_query
mysqli_more_results() - Проверка, есть ли ещё результаты в мультизапросе