sqlsrv_rows_affected — Funktion · PHP-Referenz

Signatur

sqlsrv_rows_affected(resource $stmt): int|false

Beschreibung

sqlsrv_rows_affected() ermittelt, wie viele Zeilen durch die zuletzt ausgeführte Schreiboperation (INSERT, UPDATE, DELETE) tatsächlich verändert wurden. Die Funktion ist nützlich, um nach einer Datenbankoperation zu prüfen, ob und wie viele Datensätze betroffen waren – etwa um sicherzustellen, dass ein UPDATE wirklich Zeilen aktualisiert hat.

Die Funktion gibt eine ganze Zahl zurück, die die Anzahl der betroffenen Zeilen repräsentiert. Ein Rückgabewert von -1 bedeutet, dass die Anzahl nicht bestimmbar ist (z. B. bei SELECT-Abfragen), während false auf einen Fehler hinweist. Der Wert 0 zeigt an, dass keine Zeilen verändert wurden.

Im Gegensatz zu SELECT-Abfragen, die Ergebnismengen liefern, liefern DML-Anweisungen keine Zeilen zurück, sondern nur die Anzahl der betroffenen Zeilen. sqlsrv_rows_affected() ist daher ausschließlich für Schreiboperationen sinnvoll und sollte unmittelbar nach der Ausführung der zugehörigen Anweisung aufgerufen werden.

Die Funktion gehört zur SQLSRV-Erweiterung, die für die Verbindung zu Microsoft SQL Server-Datenbanken unter PHP verwendet wird. Sie ist das SQLSRV-Äquivalent zu PDOStatement::rowCount() oder mysqli_affected_rows().

Parameter

Name	Typ	Default	Beschreibung
$stmt Pflicht	resource		Eine SQLSRV-Statement-Ressource, die durch `sqlsrv_query()` oder `sqlsrv_execute()` erzeugt wurde und eine INSERT-, UPDATE- oder DELETE-Anweisung repräsentiert.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Anzahl der geänderten Zeilen als int zurück. Der Wert -1 wird zurückgegeben, wenn die Anzahl der betroffenen Zeilen nicht bestimmbar ist (z. B. bei SELECT-Abfragen). Der Wert 0 bedeutet, dass keine Zeilen verändert wurden. Bei einem Fehler wird false zurückgegeben.

Beispiele

Anzahl aktualisierter Zeilen nach UPDATE-Abfrage

<?php
$serverName = 'localhost';
$connectionInfo = [
    'Database' => 'MeineDatenbank',
    'UID'      => 'benutzer',
    'PWD'      => 'passwort',
];

$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    die('Verbindung fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}

$sql    = 'UPDATE Produkte SET Preis = ? WHERE Kategorie = ?';
$params = [19.99, 'Elektronik'];
$stmt   = sqlsrv_query($conn, $sql, $params);

if ($stmt === false) {
    die('Abfrage fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}

$betroffeneZeilen = sqlsrv_rows_affected($stmt);

if ($betroffeneZeilen === false) {
    echo 'Fehler beim Ermitteln der betroffenen Zeilen.';
} elseif ($betroffeneZeilen === -1) {
    echo 'Die Anzahl der betroffenen Zeilen ist nicht verfügbar.';
} else {
    echo 'Anzahl aktualisierter Zeilen: ' . $betroffeneZeilen;
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Anzahl aktualisierter Zeilen: 42

Prüfung ob eine DELETE-Anweisung Zeilen gelöscht hat

<?php
$serverName = 'localhost';
$connectionInfo = [
    'Database' => 'MeineDatenbank',
    'UID'      => 'benutzer',
    'PWD'      => 'passwort',
];

$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    die('Verbindung fehlgeschlagen.');
}

$sql    = 'DELETE FROM Bestellungen WHERE Status = ? AND ErstelltAm &lt; ?';
$params = ['Abgebrochen', '2023-01-01'];
$stmt   = sqlsrv_query($conn, $sql, $params);

if ($stmt === false) {
    die('DELETE fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}

$geloeschteZeilen = sqlsrv_rows_affected($stmt);

if ($geloeschteZeilen > 0) {
    echo $geloeschteZeilen . ' Bestellung(en) erfolgreich gelöscht.';
} elseif ($geloeschteZeilen === 0) {
    echo 'Keine Bestellungen gefunden, die den Kriterien entsprechen.';
} else {
    echo 'Unbekannter Fehler oder keine Informationen verfügbar.';
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

5 Bestellung(en) erfolgreich gelöscht.

// Wichtig · Fallstricke

Wichtig: Bei SELECT-Abfragen gibt sqlsrv_rows_affected() den Wert -1 zurück, da die Anzahl der betroffenen Zeilen für Lesevorgänge nicht definiert ist. Verwende in diesem Fall sqlsrv_num_rows(), um die Anzahl der zurückgegebenen Datensätze zu ermitteln.

Prepared Statements: Wenn Anweisungen mit sqlsrv_prepare() und sqlsrv_execute() verwendet werden, muss sqlsrv_rows_affected() nach jedem sqlsrv_execute()-Aufruf aufgerufen werden, um das korrekte Ergebnis für die jeweilige Ausführung zu erhalten.

Sicherheit: Verwende stets parametrisierte Abfragen (wie in den Beispielen gezeigt), um SQL-Injection zu verhindern. Füge niemals Benutzerdaten direkt in SQL-Abfragestrings ein.

Siehe auch

sqlsrv_query sqlsrv_execute sqlsrv_num_rows sqlsrv_prepare sqlsrv_errors mysqli_affected_rows