Signatur
Beschreibung
pg_connect() stellt eine Verbindung zu einem PostgreSQL-Datenbankserver her. Der Parameter $connection_string enthält alle notwendigen Verbindungsparameter wie Host, Port, Datenbankname, Benutzername und Passwort als Schlüssel-Wert-Paare im Format keyword=value. Alternativ kann ein DSN-URI im Format postgresql://user:password@host/dbname verwendet werden.
Wird pg_connect() erneut mit identischen Parametern aufgerufen, gibt die Funktion standardmäßig das bereits bestehende Verbindungs-Handle zurück, anstatt eine neue Verbindung aufzubauen. Dieses Verhalten lässt sich mit dem Flag PGSQL_CONNECT_FORCE_NEW unterbinden, wodurch stets eine neue Verbindung erzwungen wird.
Seit PHP 8.1 ist der Rückgabetyp eine Instanz der Klasse PgSql\Connection statt einer generischen Ressource. Dies ermöglicht eine klarere Typisierung und bessere IDE-Unterstützung. Bei einem Verbindungsfehler gibt die Funktion false zurück; der Fehler kann anschließend mit pg_last_error() abgefragt werden.
Für Anwendungen mit häufigen Datenbankverbindungen (z. B. in Webapplikationen unter FPM) empfiehlt sich pg_pconnect(), das persistente Verbindungen aus einem Pool wiederverwendet und so den Verbindungsaufbau-Overhead reduziert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection_string Pflicht | string | Verbindungszeichenfolge mit Schlüssel-Wert-Paaren, z. B. "host=localhost port=5432 dbname=meindb user=admin password=geheim", oder ein URI wie "postgresql://admin:geheim@localhost/meindb". Nicht angegebene Parameter werden aus Umgebungsvariablen (z. B. PGHOST, PGUSER) oder den PostgreSQL-Standardwerten übernommen. |
|
| $flags | int | 0 | Optionale Verbindungs-Flags. Mit PGSQL_CONNECT_FORCE_NEW wird stets eine neue Verbindung geöffnet, auch wenn bereits eine mit gleichen Parametern existiert. Mit PGSQL_CONNECT_ASYNC (ab PHP 5.6) wird eine asynchrone Verbindung hergestellt. |
Rückgabewert
PgSql\Connection-Instanz zurück (vor PHP 8.1 eine Ressource vom Typ pgsql link). Bei einem Verbindungsfehler wird false zurückgegeben. Der genaue Fehler kann mit pg_last_error() abgefragt werden.Beispiele
Einfache Verbindung per Keyword-String
<?php
$conn = pg_connect('host=localhost port=5432 dbname=shop user=dbuser password=geheimwort');
if ($conn === false) {
die('Verbindung fehlgeschlagen: ' . pg_last_error());
}
echo 'Verbindung erfolgreich hergestellt.';
// Einfache Abfrage ausführen
$result = pg_query($conn, 'SELECT COUNT(*) AS anzahl FROM produkte');
$row = pg_fetch_assoc($result);
echo 'Anzahl Produkte: ' . $row['anzahl'];
pg_close($conn);Verbindung per URI mit Fehlerbehandlung und erzwungener neuer Verbindung
<?php
// Erste Verbindung
$conn1 = pg_connect('postgresql://dbuser:geheimwort@localhost:5432/shop');
// Erzwingt eine zweite, neue Verbindung statt das Handle wiederzuverwenden
$conn2 = pg_connect(
'postgresql://dbuser:geheimwort@localhost:5432/shop',
PGSQL_CONNECT_FORCE_NEW
);
if ($conn2 === false) {
fprintf(STDERR, "Verbindungsfehler: %s\n", pg_last_error());
exit(1);
}
// Verbindungsstatus prüfen
$status = pg_connection_status($conn2);
if ($status === PGSQL_CONNECTION_OK) {
echo 'Zweite Verbindung ist aktiv und bereit.' . PHP_EOL;
}
pg_close($conn1);
pg_close($conn2);// Wichtig · Fallstricke
Sicherheit: Benutzereingaben dürfen niemals ungeprüft in den $connection_string eingebettet werden, da dies zur Manipulation der Verbindungsparameter führen kann. Zugangsdaten sollten ausschließlich aus gesicherten Konfigurationsdateien oder Umgebungsvariablen bezogen und nicht im Quellcode hartcodiert werden.
Persistente Verbindungen: Für lang laufende Webapplikationen ist pg_pconnect() in Betracht zu ziehen, das Verbindungen über mehrere Requests hinweg aus einem Pool wiederverwendet. Dabei ist jedoch zu beachten, dass offene Transaktionen oder gesetzte Sitzungsparameter in einer wiederverwendeten Verbindung noch vorhanden sein können.
PHP 8.1: Der Rückgabetyp wurde von einer generischen Ressource auf die dedizierte Klasse PgSql\Connection geändert. Prüfungen wie is_resource($conn) sind daher ab PHP 8.1 nicht mehr geeignet — stattdessen sollte $conn instanceof PgSql\Connection bzw. ein strikter Vergleich mit false verwendet werden.