pg_affected_rows — Funktion · PHP-Referenz

Signatur

pg_affected_rows(PgSql\Result $result): int

Beschreibung

pg_affected_rows() liefert die Anzahl der Zeilen, die durch eine zuletzt ausgeführte SQL-Anweisung auf einer PostgreSQL-Verbindung tatsächlich verändert wurden. Die Funktion ist besonders nützlich nach INSERT-, UPDATE-, DELETE- oder MOVE-Operationen, um zu prüfen, ob die Aktion wie erwartet Datensätze betroffen hat.

Der Rückgabewert ist eine nicht-negative ganze Zahl. Bei einer Abfrage, die keine Zeilen betrifft (z. B. ein UPDATE ohne passende WHERE-Bedingung), wird 0 zurückgegeben. Bei SELECT-Abfragen liefert die Funktion in der Regel 0, da dort keine Zeilen verändert werden – für die Anzahl der zurückgelieferten Zeilen einer SELECT-Abfrage ist stattdessen pg_num_rows() zu verwenden.

Die Funktion erwartet ein PgSql\Result-Objekt, wie es von pg_query(), pg_query_params() oder pg_execute() zurückgegeben wird. Eine typische Anwendung ist die Validierung, ob ein DELETE tatsächlich Datensätze entfernt hat oder ob ein UPDATE mindestens eine Zeile aktualisiert hat.

Parameter

Name	Typ	Default	Beschreibung
$result Pflicht	PgSql\Result		Ein `PgSql\Result`-Objekt, das von `pg_query()`, `pg_query_params()` oder `pg_execute()` zurückgegeben wurde.

Rückgabewert

Typ

int

Beschreibung

Gibt die Anzahl der betroffenen Zeilen als nicht-negative ganze Zahl zurück. Gibt 0 zurück, wenn keine Zeilen betroffen waren oder die Abfrage eine SELECT-Anweisung war.

Beispiele

Anzahl gelöschter Datensätze ermitteln

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

$result = pg_query($conn, "DELETE FROM bestellungen WHERE status = 'storniert'");

if ($result === false) {
    die('Abfrage fehlgeschlagen: ' . pg_last_error($conn));
}

$anzahl = pg_affected_rows($result);
echo "Gelöschte Datensätze: " . $anzahl . PHP_EOL;

pg_close($conn);
?>

Gelöschte Datensätze: 3

UPDATE-Ergebnis überprüfen

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

$userId = 42;
$neuerName = 'Max Mustermann';

$result = pg_query_params(
    $conn,
    'UPDATE benutzer SET name = $1 WHERE id = $2',
    [$neuerName, $userId]
);

if ($result === false) {
    die('Fehler: ' . pg_last_error($conn));
}

$betroffen = pg_affected_rows($result);

if ($betroffen === 0) {
    echo 'Kein Benutzer mit der ID ' . $userId . ' gefunden.' . PHP_EOL;
} else {
    echo 'Benutzer erfolgreich aktualisiert. Betroffene Zeilen: ' . $betroffen . PHP_EOL;
}

pg_close($conn);
?>

Benutzer erfolgreich aktualisiert. Betroffene Zeilen: 1

// Wichtig · Fallstricke

Hinweis: pg_affected_rows() sollte nicht mit SELECT-Abfragen verwendet werden. Für die Anzahl der Zeilen einer SELECT-Ergebnismenge steht pg_num_rows() zur Verfügung.

Ab PHP 8.1 ist der Parameter vom Typ PgSql\Result (ein Objekt), während er in früheren PHP-Versionen eine Ressource vom Typ resource war. Der frühere Alias pg_cmdtuples() ist seit PHP 8.0 als veraltet markiert und sollte nicht mehr verwendet werden.

Wenn mehrere SQL-Befehle in einer einzigen pg_query()-Zeichenkette übergeben werden, bezieht sich pg_affected_rows() nur auf den letzten ausgeführten Befehl. Für verlässliche Ergebnisse sollten Abfragen daher einzeln abgesetzt werden.

Siehe auch

pg_query pg_query_params pg_num_rows pg_last_error pg_execute