mysqli::multi_query

mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Executa uma ou mais consultas no banco de dados

Descrição

Estilo orientado a objetos

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

Estilo procedural

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

Executa uma ou múltiplas consultas que são concatenadas com ponto-e-vírgula.

Aviso

Alerta de segurança: injeção de SQL

Se a consulta contiver qualquer entrada de variável, instruções preparadas parametrizadas devem ser usadas. Alternativamente, os dados devem ser formatados corretamente e todas as strings devem ser escapadas usando a função mysqli_real_escape_string().

Consultas são enviadas em uma chamada única ao bando de dados e processadas sequencialmente. mysqli_multi_query() espera pela finalização da primeira consulta antes de retornar o controle ao PHP. Enquanto isso, o servidor MySQL continuará processando as consultas remanescentes de forma assíncrona e disponibilizará os resultados para busca.

É recomendado usar do-while para processar consultas múltiplas. A conexão estará ocupada enquanto todas as consultas tiverem concluído e seus resultados enviados ao PHP. Nenhuma outra declaração pode ser emitida na mesma conexão até que todas as consultas sejam processadas. Para proceder à consulta seguinte, use mysqli_next_result(). Se a consulta seguinte ainda não estiver pronta, mysqli esperará pela resposta do servidor MySQL. Para verificar se há mais resultados, use mysqli_more_results().

Para consultas que produzem um conjnto de resultados, como em SELECT, SHOW, DESCRIBE ou EXPLAIN, mysqli_use_result() ou mysqli_store_result() podem ser usadas para recuperar o conjunto. Para consultas que não produzem um conjunto de resultados, as mesmas funções podem ser usadas para recuperar informação como o número de linhas afetadas.

Dica

Executar declarações CALL para procedimentos armazenados pode produzir múltiplos conjuntos de resultados. Se o procedimento armazenado contiver declarações SELECT, os conjuntos são retornados na ordem em que são produzidos enquanto o procedimento é executado. Em geral, a função que chama não sabe quantos conjuntos de resultados um procedimento irá retornar e deve estar preparada para recuperar múltiplos conjuntos. O resultado final do procedimento é um resultado de estado que não inclui nenhum conjunto. O estado indica se o procedimento teve sucesso ou se ocorreu um erro.

Parâmetros

mysql: Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
query: Uma string contendo as consultas que serão executadas. Consultas múltiplas devem ser separadas por ponto-e-vírgula (;).

Valor Retornado

Retorna false se a primeira consulta falhar. Para recuperar erros subsequentes de outras consultas, deve-se chamar mysqli_next_result() primeiro.

Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (MYSQLI_REPORT_ERROR) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como MYSQLI_REPORT_STRICT, uma exceção mysqli_sql_exception será lançada em vez do aviso.

Exemplos

Exemplo #1 Exemplo de mysqli::multi_query()

Estilo orientado a objetos

<?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";

/* executa as consultas múltiplas */
$mysqli->multi_query($query);
do {
    /* armazena o conjunto de resultados no PHP */
    if ($result = $mysqli->store_result()) {
        while ($row = $result->fetch_row()) {
            printf("%s\n", $row[0]);
        }
    }
    /* divisor de impressão */
    if ($mysqli->more_results()) {
        printf("-----------------\n");
    }
} while ($mysqli->next_result());

Estilo procedural

<?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";

/* executa as consultas múltiplas */
mysqli_multi_query($link, $query);
do {
    /* armazena o conjunto de resultados no PHP */
    if ($result = mysqli_store_result($link)) {
        while ($row = mysqli_fetch_row($result)) {
            printf("%s\n", $row[0]);
        }
    }
    /* divisor de impressão */
    if (mysqli_more_results($link)) {
        printf("-----------------\n");
    }
} while (mysqli_next_result($link));

Os exemplos acima produzirão algo semelhante a:

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

Veja Também

mysqli_query() - Executa uma consulta no banco de dados
mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados
mysqli_store_result() - Transfere um conjunto de resultados da última consulta
mysqli_next_result() - Prepara o próximo resultado de multi_query
mysqli_more_results() - Verifica se há mais algum resultado de uma consulta múltipla