query

$mysqli->query() executa uma única instrução SQL contra um banco de dados MySQL por meio de uma conexão MySQLi aberta. É a maneira mais simples de se comunicar com o MySQL a partir do PHP, sendo o ponto de partida ideal — mas, como veremos abaixo, no momento em que sua consulta contiver entrada do usuário, você deverá recorrer a prepared statements.

Esta página cobre o que query() retorna, como ler um conjunto de resultados, como ele se comporta em consultas de escrita e a armadilha de injeção SQL que você deve evitar.

Sintaxe

// Object-oriented style
$result = $mysqli->query($sql);

// Procedural style
$result = mysqli_query($mysqli, $sql);

Ambas as formas fazem a mesma coisa; o estilo OOP é utilizado ao longo desta página.

O que query() retorna

O valor de retorno depende do tipo de instrução executada:

Como a falha é sempre false, você pode ramificar com base no valor de retorno usando um simples if. Nunca assuma que uma consulta foi bem-sucedida — um nome de coluna com erro de digitação ou uma tabela ausente retornam false.

Executando uma consulta SELECT

Para um SELECT, percorra o resultado retornado e obtenha cada linha com fetch_assoc() (ou fetch_array()), depois libere o resultado ao terminar:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

// Stop early if the connection failed.
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

$result = $mysqli->query("SELECT id, name FROM users");

if ($result) {
    while ($row = $result->fetch_assoc()) {
        echo $row["id"] . ": " . $row["name"] . "\n";
    }
    $result->free();          // release the result set's memory
} else {
    echo "Query failed: " . $mysqli->error;
}

$mysqli->close();
?>

O laço while termina quando fetch_assoc() retorna null (sem mais linhas). $result->free() libera o conjunto de resultados, o que é importante em scripts de longa execução que realizam muitas consultas.

Executando INSERT, UPDATE e DELETE

Consultas de escrita não retornam um conjunto de resultados — elas retornam true em caso de sucesso. Para saber quantas linhas foram afetadas, leia $mysqli->affected_rows; para obter o id auto-incrementado de uma linha recém-inserida, leia $mysqli->insert_id:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->query("UPDATE users SET active = 1 WHERE active = 0")) {
    echo $mysqli->affected_rows . " rows updated";
} else {
    echo "Query failed: " . $mysqli->error;
}

$mysqli->close();
?>

Nunca coloque entrada do usuário diretamente em uma consulta

query() recebe uma string SQL bruta, portanto concatenar entrada do usuário nela abre a porta para injeção SQL — a falha de segurança de banco de dados mais comum na web:

// DANGEROUS — do NOT do this
$id = $_GET['id'];
$result = $mysqli->query("SELECT * FROM users WHERE id = $id");

Se um visitante enviar id=0 OR 1=1, essa consulta retornará todos os usuários. A solução é um prepared statement, que envia o SQL e os valores separadamente para que os valores nunca possam ser interpretados como SQL:

$stmt = $mysqli->prepare("SELECT * FROM users WHERE id = ?");
$stmt->bind_param("i", $_GET['id']);   // "i" = integer
$stmt->execute();
$result = $stmt->get_result();

Use query() apenas para SQL fixo sem entrada do usuário; use prepared statements para qualquer coisa que contenha valores provenientes de fora do seu código. Consulte MySQL prepared statements para um guia completo.

Resumo

• $mysqli->query() executa uma instrução SQL em uma conexão MySQLi aberta.
• Um SELECT retorna um mysqli_result que você itera com fetch_assoc(); outras instruções retornam true; qualquer falha retorna false.
• Leia affected_rows após uma escrita e insert_id após um INSERT.
• Mude para prepared statements assim que houver entrada do usuário envolvida.

Prática