Signatur
Beschreibung
pg_pconnect() öffnet eine persistente Verbindung zu einem PostgreSQL-Datenbankserver. Im Gegensatz zu pg_connect() wird die Verbindung nach dem Ende des PHP-Skripts nicht geschlossen, sondern im Verbindungspool des Webservers (z. B. Apache) gehalten und bei einem nachfolgenden Aufruf mit identischem connection_string wiederverwendet. Dadurch entfällt der Overhead für den Verbindungsaufbau bei jedem Request.
Der connection_string kann Schlüssel-Wert-Paare wie host=localhost port=5432 dbname=meindb user=nutzer password=geheim oder eine vollständige DSN-URL im Format postgresql://nutzer:passwort@host/dbname enthalten. Stimmen alle Parameter mit einer bereits offenen persistenten Verbindung überein, wird diese direkt zurückgegeben.
Persistente Verbindungen sind besonders in Hochlast-Webumgebungen sinnvoll, in denen viele kurze PHP-Requests die Datenbank treffen. Sie reduzieren den TCP-Handshake- und Authentifizierungsaufwand erheblich. Allerdings muss bedacht werden, dass Transaktionen, temporäre Tabellen oder Session-Einstellungen, die in einer früheren Anfrage gesetzt wurden, noch aktiv sein können – eine sorgfältige Verbindungsbereinigung ist deshalb Pflicht.
Mit dem optionalen Parameter flags kann PGSQL_CONNECT_FORCE_NEW übergeben werden, um eine neue persistente Verbindung zu erzwingen, auch wenn bereits eine mit gleichem connection_string existiert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection_string Pflicht | string | Verbindungszeichenkette als Schlüssel-Wert-Paare (z. B. host=localhost dbname=test user=pg) oder als PostgreSQL-DSN-URL. Alle Parameter müssen mit einer bestehenden persistenten Verbindung übereinstimmen, damit diese wiederverwendet wird. |
|
| $flags | int | 0 | Optionale Flags. Aktuell wird nur PGSQL_CONNECT_FORCE_NEW unterstützt, das das Erstellen einer neuen persistenten Verbindung erzwingt, selbst wenn bereits eine mit identischem connection_string existiert. |
Rückgabewert
PgSql\Connection-Objekt zurück (vor PHP 8.1 eine Ressource), das die persistente Datenbankverbindung repräsentiert. Bei einem Fehler – z. B. falsches Passwort oder nicht erreichbarer Server – wird false zurückgegeben.Beispiele
Einfache persistente Verbindung öffnen
<?php
$conn = pg_pconnect('host=localhost port=5432 dbname=testdb user=postgres password=geheim');
if ($conn === false) {
die('Verbindung fehlgeschlagen.');
}
$result = pg_query($conn, 'SELECT version()');
$row = pg_fetch_row($result);
echo 'PostgreSQL-Version: ' . $row[0] . PHP_EOL;
// Verbindung bleibt nach Skriptende im Pool erhalten
Neue persistente Verbindung erzwingen
<?php
// Erste persistente Verbindung
$conn1 = pg_pconnect('host=localhost dbname=testdb user=postgres password=geheim');
// Zweite Verbindung mit PGSQL_CONNECT_FORCE_NEW — erzeugt eine neue Verbindung
// auch wenn conn1 denselben connection_string verwendet
$conn2 = pg_pconnect(
'host=localhost dbname=testdb user=postgres password=geheim',
PGSQL_CONNECT_FORCE_NEW
);
if ($conn1 && $conn2) {
echo 'Zwei separate persistente Verbindungen geöffnet.' . PHP_EOL;
}
// Wichtig · Fallstricke
Transaktions-Sicherheit: Da persistente Verbindungen zwischen Requests wiederverwendet werden, können offene Transaktionen, temporäre Tabellen oder veränderte Session-Parameter aus einem vorherigen Request erhalten geblieben sein. Stellen Sie am Anfang jedes Requests sicher, dass die Verbindung in einem sauberen Zustand ist (z. B. mit pg_query($conn, 'ROLLBACK') oder durch Prüfung des Transaktionsstatus).
Verbindungsanzahl: Jeder Webserver-Worker-Prozess kann eine eigene persistente Verbindung halten. Bei vielen Worker-Prozessen kann die Gesamtanzahl offener Verbindungen die PostgreSQL-Konfigurationsgrenze (max_connections) überschreiten. Ein Connection-Pooler wie PgBouncer ist in solchen Fällen empfehlenswert.
CLI-Kontext: Im PHP-CLI-Modus verhält sich pg_pconnect() wie pg_connect(), da es keinen persistenten Prozess gibt, der die Verbindung im Pool halten könnte.