mysqli_query — Funktion · PHP-Referenz

Signatur

mysqli_query(mysqli $mysql, string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool

Beschreibung

mysqli_query() sendet eine SQL-Anweisung an den MySQL-Server und gibt das Ergebnis zurück. Bei SELECT-, SHOW-, DESCRIBE- und EXPLAIN-Abfragen wird ein mysqli_result-Objekt zurückgegeben, mit dem die Ergebniszeilen ausgelesen werden können. Bei allen anderen Anweisungen (z. B. INSERT, UPDATE, DELETE) wird bei Erfolg true, bei Fehler false zurückgegeben.

Der Parameter result_mode steuert, ob das vollständige Ergebnis sofort vom Server in den PHP-Speicher übertragen wird (MYSQLI_STORE_RESULT, Standard) oder ob die Zeilen nacheinander beim Iterieren abgerufen werden (MYSQLI_USE_RESULT). Letzteres ist bei sehr großen Ergebnismengen speicherschonender, blockiert jedoch die Verbindung, bis alle Zeilen gelesen wurden.

Die Funktion steht sowohl im prozeduralen Stil (mysqli_query($conn, $sql)) als auch im objektorientierten Stil ($conn->query($sql)) zur Verfügung. Für Abfragen mit Benutzereingaben sollte grundsätzlich mysqli_prepare() mit Prepared Statements verwendet werden, um SQL-Injection zu verhindern.

Schlägt die Abfrage fehl, gibt die Funktion false zurück. Fehlerdetails können dann über mysqli_error() oder $mysql->error abgerufen werden.

Parameter

Name	Typ	Default	Beschreibung
$mysql Pflicht	mysqli		Eine aktive MySQL-Verbindung, wie sie von `mysqli_connect()` oder `new mysqli()` zurückgegeben wird.
$query Pflicht	string		Die auszuführende SQL-Anweisung als Zeichenkette. Mehrere Anweisungen innerhalb eines einzelnen Aufrufs sind nicht erlaubt; dafür steht `mysqli_multi_query()` zur Verfügung.
$result_mode	int	MYSQLI_STORE_RESULT	Steuert die Ergebnisübertragung. `MYSQLI_STORE_RESULT` (Standard): vollständiges Ergebnis wird sofort gepuffert. `MYSQLI_USE_RESULT`: Zeilen werden einzeln vom Server abgerufen (speicherschonend, aber die Verbindung bleibt bis zum vollständigen Lesen blockiert). `MYSQLI_ASYNC`: Abfrage wird asynchron ausgeführt (nur mit mysqlnd).

Rückgabewert

Typ

mysqli_result|bool

Beschreibung

Bei SELECT-, SHOW-, DESCRIBE- und EXPLAIN-Anweisungen wird ein mysqli_result-Objekt zurückgegeben, das die Ergebnismenge repräsentiert. Bei allen anderen Anweisungen wird true bei Erfolg oder false bei einem Fehler zurückgegeben.

Beispiele

SELECT-Abfrage mit Ergebnisausgabe

<?php
$conn = mysqli_connect('localhost', 'benutzer', 'passwort', 'meine_datenbank');

if (!$conn) {
    die('Verbindungsfehler: ' . mysqli_connect_error());
}

$result = mysqli_query($conn, 'SELECT id, name, email FROM benutzer LIMIT 5');

if ($result === false) {
    die('Abfragefehler: ' . mysqli_error($conn));
}

while ($row = mysqli_fetch_assoc($result)) {
    echo $row['id'] . ': ' . $row['name'] . ' (' . $row['email'] . ')' . PHP_EOL;
}

mysqli_free_result($result);
mysqli_close($conn);

1: Max Mustermann (max@example.com) 2: Erika Musterfrau (erika@example.com)

INSERT-Abfrage im objektorientierten Stil

<?php
$conn = new mysqli('localhost', 'benutzer', 'passwort', 'meine_datenbank');

if ($conn->connect_error) {
    die('Verbindungsfehler: ' . $conn->connect_error);
}

$name  = 'Hans Beispiel';
$email = 'hans@example.com';

// WICHTIG: Eingaben escapen, besser: Prepared Statements verwenden!
$name_escaped  = mysqli_real_escape_string($conn, $name);
$email_escaped = mysqli_real_escape_string($conn, $email);

$sql = "INSERT INTO benutzer (name, email) VALUES ('$name_escaped', '$email_escaped')";

if ($conn->query($sql) === true) {
    echo 'Neuer Datensatz eingefügt, ID: ' . $conn->insert_id . PHP_EOL;
} else {
    echo 'Fehler: ' . $conn->error . PHP_EOL;
}

$conn->close();

Neuer Datensatz eingefügt, ID: 3

Speicherschonende Abfrage mit MYSQLI_USE_RESULT

<?php
$conn = new mysqli('localhost', 'benutzer', 'passwort', 'meine_datenbank');

// Bei sehr großen Ergebnismengen: Zeilen einzeln vom Server abrufen
$result = $conn->query('SELECT id, name FROM grosser_datensatz', MYSQLI_USE_RESULT);

if ($result) {
    while ($row = $result->fetch_assoc()) {
        echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
    }
    $result->free();
}

$conn->close();

// Wichtig · Fallstricke

Sicherheitswarnung: Niemals ungeprüfte Benutzereingaben direkt in eine SQL-Abfrage einbauen — das führt zu SQL-Injection-Schwachstellen. Die empfohlene Alternative ist mysqli_prepare() mit gebundenen Parametern (Prepared Statements), da diese Eingaben vollständig vom SQL-Befehl trennen und keine manuelle Maskierung erfordern.

Mehrfachanweisungen: mysqli_query() akzeptiert nur eine einzelne SQL-Anweisung pro Aufruf. Mehrere Anweisungen in einem String (durch ; getrennt) werden abgewiesen. Für solche Fälle steht mysqli_multi_query() zur Verfügung.

Ressourcenfreigabe: Das zurückgegebene mysqli_result-Objekt sollte nach der Verwendung mit mysqli_free_result() bzw. $result->free() freigegeben werden, um Speicher zu sparen — insbesondere bei großen Ergebnismengen oder vielen Abfragen.

Fehlerbehandlung: Ab PHP 8.1 löst mysqli bei Fehlern standardmäßig eine mysqli_sql_exception aus (mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT) ist die neue Voreinstellung), sodass false-Prüfungen in modernem Code oft nicht mehr nötig sind.

Siehe auch

mysqli_prepare mysqli_multi_query mysqli_fetch_assoc mysqli_fetch_array mysqli_num_rows mysqli_affected_rows mysqli_free_result mysqli_error mysqli_real_escape_string