pg_query — Funktion · PHP-Referenz

Signatur

pg_query(PgSql\Connection|string $connection_or_query, string $query = ?): PgSql\Result|false

Beschreibung

pg_query() sendet eine SQL-Abfrage an den PostgreSQL-Server und gibt bei Erfolg ein PgSql\Result-Objekt zurück, das anschließend mit Funktionen wie pg_fetch_row(), pg_fetch_assoc() oder pg_fetch_object() ausgelesen werden kann. Bei einem Fehler wird false zurückgegeben.

Die Funktion akzeptiert entweder eine explizite Verbindungsressource als ersten Parameter gefolgt von der SQL-Abfrage, oder — wenn nur ein Argument übergeben wird — direkt die SQL-Abfrage, wobei dann die zuletzt geöffnete Verbindung verwendet wird. Letzteres gilt als veraltet und sollte vermieden werden.

Es können auch mehrere SQL-Anweisungen in einem einzigen Aufruf übergeben werden, indem sie durch Semikolons getrennt werden. Dabei wird jedoch nur das Ergebnis der letzten Anweisung zurückgegeben. Für parametrisierte Abfragen — zum Schutz vor SQL-Injection — sollte stattdessen pg_query_params() verwendet werden.

pg_query() eignet sich besonders für DDL-Befehle (z. B. CREATE TABLE), einfache Leseanfragen ohne Benutzereingaben sowie das Ausführen gespeicherter Prozeduren, bei denen keine externen Parameter eingebunden werden müssen.

Parameter

Name	Typ	Default	Beschreibung
$connection_or_query Pflicht	PgSql\Connection\|string		Entweder eine aktive PostgreSQL-Verbindung (zurückgegeben von `pg_connect()` oder `pg_pconnect()`) oder — falls nur ein Argument übergeben wird — direkt die SQL-Abfrage als String (dann wird die zuletzt geöffnete Verbindung genutzt).
$query	string		Die auszuführende SQL-Abfrage. Mehrere durch Semikolon getrennte Anweisungen sind erlaubt; das Ergebnis der letzten Anweisung wird zurückgegeben. Enthält die Abfrage Benutzerdaten, sollte `pg_query_params()` verwendet werden.

Rückgabewert

Typ

PgSql\Result|false

Beschreibung

Bei Erfolg ein PgSql\Result-Objekt (vor PHP 8.1 eine Ressource), das die Abfrageergebnisse enthält und mit entsprechenden pg_fetch_*()-Funktionen verarbeitet werden kann. Bei einem Fehler wird false zurückgegeben; zusätzliche Fehlerdetails sind über pg_last_error() abrufbar.

Beispiele

Einfache SELECT-Abfrage ausführen und Ergebnisse ausgeben

<?php
$conn = pg_connect("host=localhost dbname=testdb user=postgres password=geheim");
if (!$conn) {
    die('Verbindung fehlgeschlagen: ' . pg_last_error());
}

$result = pg_query($conn, "SELECT id, name, email FROM users ORDER BY id");
if ($result === false) {
    die('Abfrage fehlgeschlagen: ' . pg_last_error($conn));
}

while ($row = pg_fetch_assoc($result)) {
    echo 'ID: ' . $row['id'] . ', Name: ' . $row['name'] . ', E-Mail: ' . $row['email'] . PHP_EOL;
}

pg_free_result($result);
pg_close($conn);

ID: 1, Name: Alice, E-Mail: alice@example.com ID: 2, Name: Bob, E-Mail: bob@example.com

Mehrere SQL-Anweisungen in einem Aufruf (Transaktion)

<?php
$conn = pg_connect("host=localhost dbname=testdb user=postgres password=geheim");
if (!$conn) {
    die('Verbindung fehlgeschlagen.');
}

// Mehrere Anweisungen auf einmal senden
$sql = "
    BEGIN;
    UPDATE accounts SET balance = balance - 100 WHERE id = 1;
    UPDATE accounts SET balance = balance + 100 WHERE id = 2;
    COMMIT;
";

$result = pg_query($conn, $sql);
if ($result === false) {
    echo 'Transaktion fehlgeschlagen: ' . pg_last_error($conn);
} else {
    echo 'Transaktion erfolgreich abgeschlossen.';
}

pg_close($conn);

Transaktion erfolgreich abgeschlossen.

// Wichtig · Fallstricke

Sicherheitshinweis (SQL-Injection): pg_query() bietet keinen eingebauten Schutz vor SQL-Injection. Werden Benutzereingaben in die Abfrage eingebettet, muss zwingend pg_query_params() mit Platzhaltern verwendet werden. Alternativ können Werte mit pg_escape_string() oder pg_escape_literal() maskiert werden, was jedoch fehleranfälliger ist.

Veraltete Einzel-Argument-Syntax: Das Übergeben nur der SQL-Abfrage ohne explizite Verbindung (Nutzung der zuletzt geöffneten Verbindung) ist seit PHP 8.1 als veraltet markiert und sollte nicht mehr verwendet werden.

Mehrere Statements: Wenn mehrere SQL-Anweisungen durch Semikolon getrennt übergeben werden, wird nur das Ergebnis-Objekt der letzten Anweisung zurückgegeben. Zwischenergebnisse sind nicht abrufbar.

Ressource freigeben: Nach der Verarbeitung sollte das Ergebnis-Objekt mit pg_free_result() freigegeben werden, um Speicher zu sparen — besonders bei großen Ergebnismengen.

Siehe auch

pg_connect pg_query_params pg_fetch_assoc pg_fetch_row pg_fetch_object pg_last_error pg_free_result pg_escape_literal pg_prepare