Signatur
Beschreibung
pg_ping() testet eine bestehende PostgreSQL-Verbindung auf ihre Funktionstüchtigkeit. Ist die Verbindung unterbrochen oder in einem fehlerhaften Zustand, versucht die Funktion intern, die Verbindung automatisch zurückzusetzen (reset). Nur wenn dieser Wiederherstellungsversuch ebenfalls scheitert, gibt die Funktion false zurück.
Die Funktion ist besonders nützlich in langlaufenden Skripten oder in Umgebungen, in denen persistente Verbindungen (pg_pconnect()) genutzt werden. Hier kann eine zuvor hergestellte Verbindung durch Timeouts, Datenbankneustarts oder Netzwerkprobleme stillschweigend getrennt worden sein.
Im Gegensatz zu einem reinen Verbindungstest sendet pg_ping() aktiv eine Anfrage an den Server, sodass sichergestellt wird, dass die Verbindung wirklich antwortet und nicht nur lokal als offen markiert ist. Das Ergebnis sollte vor kritischen Datenbankoperationen geprüft werden, um Folgefehler zu vermeiden.
Wird kein Parameter übergeben, arbeitet die Funktion mit der zuletzt geöffneten Verbindung. In modernem Code empfiehlt es sich jedoch stets, das Verbindungs-Objekt explizit zu übergeben.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection | PgSql\Connection | Eine PostgreSQL-Verbindungsinstanz, die von pg_connect() oder pg_pconnect() zurückgegeben wurde. Seit PHP 8.1 ist dies ein PgSql\Connection-Objekt (zuvor eine Ressource). Wird der Parameter weggelassen, verwendet PHP die zuletzt geöffnete Verbindung. |
Rückgabewert
true zurück, wenn die Verbindung aktiv ist oder erfolgreich wiederhergestellt werden konnte. Gibt false zurück, wenn die Verbindung nicht erreichbar ist und auch die automatische Wiederherstellung fehlgeschlagen ist.Beispiele
Einfache Verbindungsprüfung vor einer Datenbankabfrage
<?php
$conn = pg_connect('host=localhost dbname=meinedb user=postgres password=geheim');
if (!$conn) {
die('Verbindung konnte nicht hergestellt werden.');
}
// Prüfen, ob die Verbindung noch aktiv ist
if (!pg_ping($conn)) {
die('Datenbankverbindung ist nicht mehr verfügbar.');
}
$result = pg_query($conn, 'SELECT COUNT(*) FROM bestellungen');
$row = pg_fetch_row($result);
echo 'Anzahl Bestellungen: ' . $row[0];Robuste Nutzung mit persistenter Verbindung und automatischer Wiederherstellung
<?php
function getDbConnection(): PgSql\Connection {
static $conn = null;
if ($conn === null) {
$conn = pg_pconnect('host=localhost dbname=meinedb user=postgres password=geheim');
}
// Verbindung prüfen und ggf. neu aufbauen
if ($conn === false || !pg_ping($conn)) {
$conn = pg_connect(
'host=localhost dbname=meinedb user=postgres password=geheim',
PGSQL_CONNECT_FORCE_NEW
);
if (!$conn) {
throw new \RuntimeException('Keine Datenbankverbindung möglich.');
}
}
return $conn;
}
try {
$conn = getDbConnection();
$result = pg_query($conn, "SELECT NOW() AS serverzeit");
$row = pg_fetch_assoc($result);
echo 'Serverzeit: ' . $row['serverzeit'];
} catch (\RuntimeException $e) {
echo 'Fehler: ' . $e->getMessage();
}// Wichtig · Fallstricke
Persistente Verbindungen: Bei der Verwendung von pg_pconnect() sollte pg_ping() stets vor dem ersten Datenbankzugriff aufgerufen werden, da persistente Verbindungen zwischen verschiedenen Requests zwischengespeichert werden und in dieser Zeit unterbrochen worden sein können.
Automatischer Reset: Der interne Reset-Versuch von pg_ping() entspricht einem Aufruf von pg_reset(). Transaktionen, die sich vor dem Reset in einem fehlerhaften Zustand befanden, werden dabei abgebrochen. Zustandsinformationen wie temporäre Tabellen oder Sitzungsvariablen gehen bei einem Reset verloren.
PHP 8.1: Ab PHP 8.1 wurde der Ressource-Typ für PostgreSQL-Verbindungen durch das Objekt PgSql\Connection ersetzt. Code, der auf den alten Ressource-Typ prüft (z. B. mit is_resource()), muss entsprechend angepasst werden.