pg_result_status — Funktion · PHP-Referenz

Signatur

pg_result_status(PgSql\Result $result, int $mode = PGSQL_STATUS_LONG): string|int

Beschreibung

pg_result_status() ermittelt den Ausführungsstatus eines PostgreSQL-Abfrageergebnisses. Je nach gewähltem Modus liefert die Funktion entweder eine ganzzahlige Statuskonstante (PGSQL_STATUS_LONG) oder einen vom PostgreSQL-Server gesendeten Statusstring wie INSERT, SELECT oder UPDATE (PGSQL_STATUS_STRING).

Der Standardmodus PGSQL_STATUS_LONG gibt eine der vordefinierten Konstanten zurück, z. B. PGSQL_COMMAND_OK (Befehl erfolgreich ohne Ergebnismenge), PGSQL_TUPLES_OK (Abfrage liefert Zeilen) oder PGSQL_FATAL_ERROR (schwerwiegender Fehler). Diese Konstanten eignen sich gut für programmatische Auswertungen in Fallunterscheidungen.

Der Modus PGSQL_STATUS_STRING gibt den vom Server gemeldeten Befehlsstatus als Zeichenkette zurück, etwa "INSERT 0 1" oder "SELECT 5". Das ist nützlich, wenn man z. B. die Anzahl betroffener Zeilen aus dem Statusstring parsen möchte oder den Statustext direkt protokollieren will.

Die Funktion wird vor allem zur Fehlerbehandlung und zur Unterscheidung verschiedener Ergebnistypen (z. B. nach einem COPY-Befehl) eingesetzt.

Parameter

Name	Typ	Default	Beschreibung
$result Pflicht	PgSql\Result		Eine PostgreSQL-Ergebnisressource, wie sie von `pg_query()`, `pg_query_params()` oder ähnlichen Funktionen zurückgegeben wird.
$mode	int	PGSQL_STATUS_LONG	Bestimmt die Art des Rückgabewerts. `PGSQL_STATUS_LONG` (Standard) liefert eine ganzzahlige Statuskonstante; `PGSQL_STATUS_STRING` liefert den Statusstring des Servers.

Rückgabewert

Typ

string|int

Beschreibung

Bei PGSQL_STATUS_LONG wird eine der Konstanten PGSQL_EMPTY_QUERY, PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_OUT, PGSQL_COPY_IN, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR oder PGSQL_FATAL_ERROR als int zurückgegeben. Bei PGSQL_STATUS_STRING wird der vom PostgreSQL-Server gesendete Statusstring als string zurückgegeben.

Beispiele

Status einer SELECT-Abfrage prüfen

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

$result = pg_query($conn, 'SELECT id, name FROM users LIMIT 5');
if (!$result) {
    die('Abfrage fehlgeschlagen: ' . pg_last_error($conn));
}

$status = pg_result_status($result);

if ($status === PGSQL_TUPLES_OK) {
    echo 'Abfrage erfolgreich, Zeilen gefunden.' . PHP_EOL;
    while ($row = pg_fetch_assoc($result)) {
        echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
    }
} elseif ($status === PGSQL_COMMAND_OK) {
    echo 'Befehl erfolgreich ausgeführt (keine Ergebnismenge).' . PHP_EOL;
} else {
    echo 'Unerwarteter Status: ' . $status . PHP_EOL;
}

pg_free_result($result);
pg_close($conn);

Abfrage erfolgreich, Zeilen gefunden. 1: Alice 2: Bob ...

Statusstring nach einem INSERT auslesen

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

$result = pg_query_params(
    $conn,
    'INSERT INTO users (name, email) VALUES ($1, $2)',
    ['Charlie', 'charlie@example.com']
);

if (!$result) {
    die('INSERT fehlgeschlagen: ' . pg_last_error($conn));
}

// Statusstring direkt vom Server abrufen
$statusString = pg_result_status($result, PGSQL_STATUS_STRING);
echo 'Server-Status: ' . $statusString . PHP_EOL;
// z. B.: "INSERT 0 1" — die letzte Zahl gibt die Anzahl eingefügter Zeilen an

$statusCode = pg_result_status($result, PGSQL_STATUS_LONG);
if ($statusCode === PGSQL_COMMAND_OK) {
    echo 'Einfügen war erfolgreich.' . PHP_EOL;
}

pg_free_result($result);
pg_close($conn);

Server-Status: INSERT 0 1 Einfügen war erfolgreich.

// Wichtig · Fallstricke

Statuskonstanten im Überblick:

PGSQL_EMPTY_QUERY – leere Abfrage wurde gesendet
PGSQL_COMMAND_OK – Befehl erfolgreich, keine Ergebniszeilen (z. B. INSERT, UPDATE, DELETE)
PGSQL_TUPLES_OK – Abfrage erfolgreich, Ergebniszeilen vorhanden (z. B. SELECT)
PGSQL_COPY_OUT – COPY-Datenstrom vom Server begonnen
PGSQL_COPY_IN – COPY-Datenstrom zum Server begonnen
PGSQL_BAD_RESPONSE – unverständliche Serverantwort
PGSQL_NONFATAL_ERROR – nicht-schwerwiegender Fehler (z. B. Warnung)
PGSQL_FATAL_ERROR – schwerwiegender Fehler

Ab PHP 8.1 ist $result ein PgSql\Result-Objekt; in früheren Versionen war es eine Ressource (resource). Der Code bleibt funktional kompatibel, da PHP die Konvertierung intern handhabt.

Siehe auch

pg_query pg_query_params pg_last_error pg_affected_rows pg_num_rows pg_free_result