PDO_PGSQL DSN — Funktion · PHP-Referenz

Signatur

pgsql:host=...;port=...;dbname=...;user=...;password=...;sslmode=...

Beschreibung

Der PDO_PGSQL DSN (Data Source Name) definiert, wie PHP über den PDO-Treiber eine Verbindung zu einer PostgreSQL-Datenbank aufbaut. Der DSN beginnt immer mit dem Präfix pgsql:, gefolgt von einer Reihe von Schlüssel-Wert-Paaren, die durch Semikolon getrennt sind.

Der DSN kann alle Parameter enthalten, die auch die PostgreSQL-Bibliothek libpq kennt, also z. B. host, port, dbname, user, password und sslmode. Alternativ kann statt eines strukturierten DSN auch ein vollständiger PostgreSQL-Connection-String im Format pgsql:host=... port=... dbname=... (Leerzeichen als Trennzeichen) übergeben werden.

Wird der DSN als leerer String (pgsql:) übergeben, verbindet sich PDO über die Standard-Umgebungsvariablen von libpq (z. B. PGHOST, PGDATABASE, PGUSER). Das ist nützlich in containerisierten Umgebungen, in denen Verbindungsparameter als Umgebungsvariablen bereitgestellt werden.

Für verschlüsselte Verbindungen steht der Parameter sslmode zur Verfügung, der Werte wie disable, allow, prefer, require, verify-ca oder verify-full akzeptiert. Sensible Zugangsdaten sollten nie direkt im Quellcode stehen, sondern aus Umgebungsvariablen oder einer gesicherten Konfigurationsdatei gelesen werden.

Parameter

Name	Typ	Default	Beschreibung
$host	string	localhost	Hostname oder IP-Adresse des PostgreSQL-Servers. Bei Unix-Socket-Verbindungen kann auch ein Verzeichnispfad angegeben werden.
$port	int	5432	TCP-Port, auf dem der PostgreSQL-Server lauscht.
$dbname	string		Name der Ziel-Datenbank. Wird dieser Parameter weggelassen, wird der Benutzername als Datenbankname verwendet.
$user	string		Benutzername für die Authentifizierung. Kann alternativ als zweiter Parameter des `PDO`-Konstruktors übergeben werden.
$password	string		Passwort für die Authentifizierung. Kann alternativ als dritter Parameter des `PDO`-Konstruktors übergeben werden.
$sslmode	string	prefer	SSL-Modus der Verbindung. Mögliche Werte: `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`.

Rückgabewert

Typ

Beispiele

Einfache Verbindung zu einer lokalen PostgreSQL-Datenbank

<?php
$dsn  = 'pgsql:host=localhost;port=5432;dbname=meine_db';
$user = 'db_benutzer';
$pass = 'geheimes_passwort';

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);
    echo "Verbindung erfolgreich hergestellt.\n";

    $stmt = $pdo->query('SELECT version()');
    echo $stmt->fetchColumn();
} catch (PDOException $e) {
    // Fehlermeldung NICHT direkt ausgeben – nur loggen!
    error_log('Datenbankfehler: ' . $e->getMessage());
    echo 'Verbindung fehlgeschlagen.';
}

Verbindung erfolgreich hergestellt. PostgreSQL 15.3 on x86_64-pc-linux-gnu, compiled by gcc ...

Verbindung über Umgebungsvariablen und SSL erzwingen

<?php
// Zugangsdaten aus Umgebungsvariablen lesen (sicherer Ansatz)
$host   = getenv('PGHOST')     ?: 'db.example.com';
$port   = getenv('PGPORT')     ?: '5432';
$dbname = getenv('PGDATABASE') ?: 'produktion';
$user   = getenv('PGUSER')     ?: 'app_user';
$pass   = getenv('PGPASSWORD') ?: '';

$dsn = sprintf(
    'pgsql:host=%s;port=%s;dbname=%s;sslmode=require',
    $host, $port, $dbname
);

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);

    $stmt = $pdo->prepare('SELECT id, name FROM benutzer WHERE aktiv = :aktiv');
    $stmt->execute([':aktiv' => true]);

    foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) as $zeile) {
        echo $zeile['id'] . ': ' . $zeile['name'] . "\n";
    }
} catch (PDOException $e) {
    error_log($e->getMessage());
}

1: Alice 2: Bob

Verbindung über einen Unix-Domain-Socket

<?php
// Verbindung über lokalen Unix-Socket (kein Netzwerk, schneller)
$dsn = 'pgsql:host=/var/run/postgresql;dbname=local_db';

try {
    $pdo = new PDO($dsn, 'postgres', '', [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);
    echo "Socket-Verbindung erfolgreich.\n";
} catch (PDOException $e) {
    error_log($e->getMessage());
}

Socket-Verbindung erfolgreich.

// Wichtig · Fallstricke

Sicherheit: Passwörter und Benutzernamen sollten niemals direkt im Quellcode (und damit im Versionskontrollsystem) stehen. Nutze Umgebungsvariablen, .env-Dateien (außerhalb des Web-Roots) oder einen Secret-Manager.

SSL: In Produktionsumgebungen empfiehlt sich mindestens sslmode=require, besser verify-full mit einem vertrauenswürdigen CA-Zertifikat, um Man-in-the-Middle-Angriffe zu verhindern.

Fehlerbehandlung: Fange PDOException-Fehler ab und gib keine internen Fehlermeldungen an den Endbenutzer aus – logge sie stattdessen serverseitig. Der Klartext einer PDOException kann Zugangsdaten aus dem DSN enthalten.

Zeichenkodierung: PostgreSQL verwendet standardmäßig die Datenbank-Enkodierung. Stelle sicher, dass Client und Server dieselbe Kodierung (am besten UTF-8) verwenden, um Zeichensatzprobleme zu vermeiden.

Siehe auch

PDO PDO::__construct PDO::prepare PDO_MYSQL DSN PDO::ATTR_ERRMODE