Pdo\Pgsql — Klasse · PHP-Referenz

Signatur

class Pdo\Pgsql extends PDO

Beschreibung

Pdo\Pgsql ist die typisierte, native PDO-Unterklasse für PostgreSQL-Verbindungen, die seit PHP 8.1 als dedizierte Klasse statt des generischen PDO-Objekts verwendet werden kann. Sie kapselt den pgsql-Treiber und enthält PostgreSQL-spezifische Konstanten sowie Methoden, die über die generische PDO-Schnittstelle hinausgehen.

Im Gegensatz zu einer normalen PDO-Instanz mit dem DSN-Präfix pgsql: liefert Pdo\Pgsql durch statische Typisierung bessere IDE-Unterstützung und ermöglicht den direkten Zugriff auf Methoden wie escapeIdentifier() oder copyFromArray(), ohne auf unsichere String-Methoden zurückgreifen zu müssen.

Der integrierte SQL-Parser versteht PostgreSQL-spezifische Syntax wie Dollar-Quoting ($$...$$), Array-Typen, JSON-Operatoren sowie die ::-Cast-Syntax, was verhindert, dass der Treiber platzhalterähnliche Zeichen in solchen Konstrukten fälschlicherweise als Parameter interpretiert.

Sinnvoll ist der Einsatz dieser Klasse immer dann, wenn PostgreSQL-exklusive Features wie COPY, LISTEN/NOTIFY, Large Objects oder komplexe Typen genutzt werden sollen und gleichzeitig typsicherer Code gewünscht wird.

Parameter

Name	Typ	Default	Beschreibung
$dsn Pflicht	string		Data Source Name im Format `pgsql:host=localhost;port=5432;dbname=mydb`. Alternativ kann ein vollständiger libpq-Connection-String übergeben werden.
$username	string\|null	null	Datenbankbenutzername. Kann auch im DSN enthalten sein.
$password	string\|null	null	Datenbankpasswort. Sollte nicht im DSN als Klartext stehen, sondern hier übergeben oder via `~/.pgpass` bereitgestellt werden.
$options	array\|null	null	Treiber- und PDO-Optionen als assoziatives Array, z. B. `[PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]` oder PostgreSQL-spezifische Optionen wie `[PDO::PGSQL_ATTR_DISABLE_PREPARES => true]`.

Beispiele

Verbindungsaufbau und einfache Abfrage

<?php
use Pdo\Pgsql;

$pdo = new Pgsql(
    dsn: 'pgsql:host=127.0.0.1;port=5432;dbname=shop',
    username: 'app_user',
    password: 'geheim',
    options: [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES   => false,
    ]
);

$stmt = $pdo->prepare('SELECT id, name, price::numeric FROM products WHERE category_id = :cat');
$stmt->execute([':cat' => 3]);

foreach ($stmt->fetchAll() as $row) {
    printf("[%d] %s – %.2f €\n", $row['id'], $row['name'], $row['price']);
}

[12] Laptop – 999.00 € [17] Maus – 19.99 €

COPY-Import aus einem PHP-Array mit copyFromArray()

<?php
use Pdo\Pgsql;

$pdo = new Pgsql('pgsql:host=localhost;dbname=warehouse', 'user', 'pass', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

// Tabelle: CREATE TABLE imports (sku text, qty int, price numeric);
$rows = [
    "SKU-001\t100\t9.99",
    "SKU-002\t50\t14.50",
    "SKU-003\t200\t4.75",
];

// copyFromArray() überträgt Daten hocheffizient über das COPY-Protokoll
$pdo->copyFromArray(
    tableName: 'imports',
    rows:      $rows,
    separator: "\t"
);

echo "Import abgeschlossen, " . count($rows) . " Zeilen eingefügt.\n";

Import abgeschlossen, 3 Zeilen eingefügt.

Bezeichner sicher escapen mit escapeIdentifier()

<?php
use Pdo\Pgsql;

$pdo = new Pgsql('pgsql:host=localhost;dbname=mydb', 'user', 'pass');

// Dynamischer Tabellenname – NIEMALS direkt interpolieren!
$userInput = 'orders 2024'; // enthält Leerzeichen
$safeIdent = $pdo->escapeIdentifier($userInput);

// Ergibt: "orders 2024"
echo $safeIdent . "\n";

$sql  = "SELECT * FROM {$safeIdent} WHERE status = :status";
$stmt = $pdo->prepare($sql);
$stmt->execute([':status' => 'open']);
$rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
echo count($rows) . " offene Bestellungen gefunden.\n";

"orders 2024" 7 offene Bestellungen gefunden.

// Wichtig · Fallstricke

Sicherheit: Verwende stets Prepared Statements für Benutzereingaben in Werten. Für dynamische Bezeichner (Tabellen-/Spaltennamen) steht escapeIdentifier() bereit — diese dürfen niemals ungeprüft in SQL-Strings interpoliert werden, da Prepared Statements Bezeichner nicht parametrisieren können.

Passwörter: Das Passwort sollte nicht im DSN-String stehen, da es sonst in Logs oder Exception-Messages erscheinen kann. Übergib es als dritten Konstruktorparameter oder nutze eine .pgpass-Datei bzw. Umgebungsvariablen.

Klassen-Voraussetzung: Pdo\Pgsql als typisierte Unterklasse ist erst ab PHP 8.1 verfügbar. In älteren PHP-Versionen muss die generische PDO-Klasse mit dem DSN-Präfix pgsql: genutzt werden; die Funktionalität ist dieselbe, aber die Klasse trägt keinen eigenen Typ.

SSL: Für Produktivverbindungen sollte TLS erzwungen werden: pgsql:host=db.example.com;dbname=prod;sslmode=require. Die Option sslmode=verify-full bietet den stärksten Schutz gegen Man-in-the-Middle-Angriffe.

Siehe auch

PDO PDOStatement PDOException Pdo\Pgsql::copyFromArray Pdo\Pgsql::escapeIdentifier PDO::prepare PDO::exec