Signatur
Beschreibung
pg_transaction_status() fragt den aktuellen Transaktionsstatus der übergebenen PostgreSQL-Verbindung ab und gibt einen der vordefinierten Statuscodes zurück. Dies ist nützlich, um vor dem Absenden weiterer Abfragen zu prüfen, ob sich die Verbindung in einem definierten, konsistenten Zustand befindet.
Die Funktion gibt eine der folgenden Konstanten zurück: PGSQL_TRANSACTION_IDLE (keine aktive Transaktion), PGSQL_TRANSACTION_ACTIVE (eine Abfrage ist aktiv), PGSQL_TRANSACTION_INTRANS (innerhalb einer Transaktion), PGSQL_TRANSACTION_INERROR (Transaktion mit Fehler, muss zurückgerollt werden) und PGSQL_TRANSACTION_UNKNOWN (Verbindung fehlerhaft oder Status unbekannt).
Besonders in langlebigen Prozessen oder nach Fehlerszenarien ist es ratsam, den Status zu prüfen, bevor neue Datenbank-Operationen gestartet werden. So kann vermieden werden, dass Abfragen innerhalb einer fehlerhaften Transaktion ausgeführt werden, was zu unerwarteten Datenbankzuständen führen könnte.
Im Gegensatz zu pg_query() oder ähnlichen Funktionen sendet pg_transaction_status() selbst keine Abfrage an den Server, sondern liest den intern gecachten Status der Client-Bibliothek (libpq). Der Status kann sich daher geringfügig von dem des Servers unterscheiden, wenn asynchrone Operationen verwendet werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | PgSql\Connection | Eine aktive PostgreSQL-Verbindungsinstanz, die zuvor mit pg_connect() oder pg_pconnect() erstellt wurde. |
Rückgabewert
PGSQL_TRANSACTION_IDLE (0), PGSQL_TRANSACTION_ACTIVE (1), PGSQL_TRANSACTION_INTRANS (2), PGSQL_TRANSACTION_INERROR (3) oder PGSQL_TRANSACTION_UNKNOWN (4).Beispiele
Transaktionsstatus vor einer Abfrage prüfen
<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');
if (!$conn) {
die('Verbindung fehlgeschlagen');
}
$status = pg_transaction_status($conn);
if ($status === PGSQL_TRANSACTION_IDLE) {
echo "Verbindung ist idle – bereit für neue Abfragen.\n";
} elseif ($status === PGSQL_TRANSACTION_INTRANS) {
echo "Aktive Transaktion läuft.\n";
} elseif ($status === PGSQL_TRANSACTION_INERROR) {
echo "Fehlerhafte Transaktion – führe ROLLBACK durch.\n";
pg_query($conn, 'ROLLBACK');
} elseif ($status === PGSQL_TRANSACTION_UNKNOWN) {
echo "Verbindung fehlerhaft oder Status unbekannt.\n";
} else {
echo "Anderer Status: " . $status . "\n";
}Status nach BEGIN und nach einem Fehler kontrollieren
<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');
// Transaktion starten
pg_query($conn, 'BEGIN');
echo pg_transaction_status($conn); // Erwartet: 2 (PGSQL_TRANSACTION_INTRANS)
echo "\n";
// Absichtlich fehlerhafte Abfrage ausführen
@pg_query($conn, 'SELECT * FROM nicht_existierende_tabelle');
echo pg_transaction_status($conn); // Erwartet: 3 (PGSQL_TRANSACTION_INERROR)
echo "\n";
// Transaktion zurückrollen
pg_query($conn, 'ROLLBACK');
echo pg_transaction_status($conn); // Erwartet: 0 (PGSQL_TRANSACTION_IDLE)
echo "\n";// Wichtig · Fallstricke
Achtung: Der zurückgegebene Status basiert auf dem internen Cache der libpq-Bibliothek und spiegelt nicht unbedingt den tatsächlichen Serverzustand wider, wenn asynchrone Abfragen (pg_send_query() etc.) verwendet werden. In solchen Szenarien sollte der Status erst nach Abschluss aller ausstehenden Ergebnisse abgefragt werden.
Wenn der Status PGSQL_TRANSACTION_INERROR zurückgegeben wird, müssen alle weiteren Abfragen fehlschlagen, bis ein ROLLBACK durchgeführt wurde. Das Ignorieren dieses Zustands kann zu schwer nachvollziehbaren Datenbankfehlern führen.
Ab PHP 8.1 wird der Verbindungsparameter als PgSql\Connection-Objekt erwartet; zuvor war es eine Ressource vom Typ resource.