Signatur
Beschreibung
pg_connection_status() prüft den Zustand einer bestehenden PostgreSQL-Verbindung und gibt einen Integer-Statuscode zurück. Damit lässt sich feststellen, ob eine Verbindung noch funktionsfähig ist oder ob ein Fehler aufgetreten ist, der eine Neuverbindung erfordert.
Die Funktion gibt eine der beiden Konstanten zurück: PGSQL_CONNECTION_OK (Verbindung ist aktiv und verwendbar) oder PGSQL_CONNECTION_BAD (Verbindung ist fehlerhaft oder unterbrochen). In seltenen Fällen können bei asynchronen Verbindungen weitere Statuscodes auftreten.
Typische Einsatzgebiete sind persistente Verbindungen (pg_pconnect()), bei denen regelmäßig überprüft werden sollte, ob die Verbindung noch intakt ist, sowie Fehlerbehandlungsroutinen nach einem Netzwerkausfall oder einem Datenbankserverneustart. Im Fehlerfall kann pg_connection_reset() einen Neuverbindungsversuch unternehmen.
Es ist zu beachten, dass pg_connection_status() nur den intern gespeicherten Zustand abfragt und keine aktive Netzwerkkommunikation durchführt. Ein PGSQL_CONNECTION_OK garantiert daher nicht zwingend, dass die Verbindung beim nächsten Query noch gültig ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | PgSql\Connection | Eine aktive PostgreSQL-Verbindungsinstanz, wie sie von pg_connect() oder pg_pconnect() zurückgegeben wird. |
Rückgabewert
PGSQL_CONNECTION_OK (0) zurück, wenn die Verbindung einwandfrei ist, oder PGSQL_CONNECTION_BAD (1), wenn die Verbindung fehlerhaft ist. Weitere interne Statuscodes sind bei asynchronen Verbindungen möglich, aber in der Praxis selten.Beispiele
Verbindungsstatus nach pg_connect() prüfen
<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');
if (!$conn) {
die('Verbindung konnte nicht hergestellt werden.');
}
$status = pg_connection_status($conn);
if ($status === PGSQL_CONNECTION_OK) {
echo 'Verbindung ist aktiv und bereit.';
} else {
echo 'Verbindung ist fehlerhaft (Status: ' . $status . ').';
}
pg_close($conn);Automatische Neuverbindung bei fehlerhafter Verbindung
<?php
$conn = pg_pconnect('host=localhost dbname=testdb user=postgres password=secret');
if (!$conn) {
die('Persistente Verbindung konnte nicht hergestellt werden.');
}
// Verbindungsstatus prüfen und ggf. zurücksetzen
if (pg_connection_status($conn) !== PGSQL_CONNECTION_OK) {
echo 'Verbindung unterbrochen – versuche Neuverbindung...' . PHP_EOL;
if (pg_connection_reset($conn)) {
echo 'Neuverbindung erfolgreich.';
} else {
die('Neuverbindung fehlgeschlagen.');
}
} else {
echo 'Verbindung ist in Ordnung.';
}
$result = pg_query($conn, 'SELECT version()');
if ($result) {
$row = pg_fetch_row($result);
echo PHP_EOL . 'PostgreSQL-Version: ' . $row[0];
}// Wichtig · Fallstricke
Wichtiger Hinweis: Die Funktion führt keine aktive Netzwerkverbindungsprüfung durch. Der Status PGSQL_CONNECTION_OK bedeutet nur, dass der interne Zustand der Verbindung als gut eingestuft ist – die tatsächliche Netzwerkverbindung kann dennoch unterbrochen sein. Ein wirklicher Verbindungstest erfordert das Ausführen einer einfachen Abfrage wie SELECT 1.
Ab PHP 8.1 ist der Typ des Parameters von resource auf PgSql\Connection geändert worden. Älterer Code, der noch resource-Variablen verwendet, sollte entsprechend angepasst werden.