pg_send_query — Funktion · PHP-Referenz

Signatur

pg_send_query(PgSql\Connection $connection, string $query): int|false

Beschreibung

pg_send_query() übermittelt eine oder mehrere SQL-Anweisungen an den PostgreSQL-Server, kehrt aber sofort zurück, ohne auf die Antwort zu warten. Das Ergebnis wird später mit pg_get_result() abgerufen. Dieses Verfahren ermöglicht es, zwischen dem Absetzen der Anfrage und dem Abrufen des Resultats andere Aufgaben zu erledigen – z. B. weitere asynchrone Abfragen zu starten oder IO-Operationen durchzuführen.

Im Gegensatz zu pg_query(), das blockiert, bis der Server das Ergebnis zurückliefert, ist pg_send_query() nicht-blockierend. Mit pg_connection_busy() kann geprüft werden, ob die Verbindung noch auf ein Ergebnis wartet, und mit pg_cancel_query() kann eine laufende Abfrage abgebrochen werden.

Werden mehrere SQL-Anweisungen durch Semikolon getrennt übergeben, sendet der Server die Resultate der Reihe nach; alle können einzeln mit wiederholten Aufrufen von pg_get_result() abgeholt werden. Dabei ist jedoch zu beachten, dass keine parameterisierten Abfragen möglich sind – wer Parameter übergeben möchte, sollte stattdessen pg_send_query_params() verwenden.

Typische Einsatzgebiete sind Performance-kritische Anwendungen, die mehrere unabhängige Datenbankoperationen quasi-parallel ausführen wollen, sowie Situationen, in denen das Ergebnis erst zu einem späteren Zeitpunkt im Programmfluss benötigt wird.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Verbindungsinstanz, die z. B. von `pg_connect()` oder `pg_pconnect()` zurückgegeben wurde.
$query Pflicht	string		Die SQL-Abfrage oder mehrere durch Semikolon getrennte Abfragen, die asynchron ausgeführt werden sollen. Enthält die Abfrage Benutzereingaben, muss zwingend `pg_send_query_params()` statt direkter Stringinterpolation verwendet werden.

Rückgabewert

Typ

int|false

Beschreibung

Gibt 1 (bzw. einen wahren Wert) zurück, wenn die Abfrage erfolgreich in die Sendewarteschlange eingereiht wurde, oder false bei einem Fehler (z. B. bei fehlender oder beschädigter Verbindung). Ein erfolgreicher Rückgabewert bedeutet nicht, dass die Abfrage auf dem Server erfolgreich ausgeführt wurde – das Ergebnis wird erst durch pg_get_result() ermittelt.

Beispiele

Einfache asynchrone Abfrage senden und Ergebnis abrufen

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

// Abfrage asynchron absenden
$sent = pg_send_query($conn, 'SELECT id, name FROM users LIMIT 5');
if (!$sent) {
    die('Abfrage konnte nicht gesendet werden: ' . pg_last_error($conn));
}

// Hier könnten andere Aufgaben erledigt werden ...

// Auf das Ergebnis warten und abrufen
while ($result = pg_get_result($conn)) {
    if (pg_result_status($result) !== PGSQL_TUPLES_OK) {
        echo 'Fehler: ' . pg_result_error($result) . PHP_EOL;
        continue;
    }
    while ($row = pg_fetch_assoc($result)) {
        echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
    }
    pg_free_result($result);
}

pg_close($conn);

1: Alice 2: Bob 3: Charlie 4: Dave 5: Eve

Mehrere Abfragen in einem Aufruf senden

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

// Zwei Abfragen durch Semikolon getrennt
$sent = pg_send_query(
    $conn,
    'SELECT COUNT(*) AS anzahl FROM users; SELECT COUNT(*) AS anzahl FROM orders'
);

if (!$sent) {
    die('Senden fehlgeschlagen: ' . pg_last_error($conn));
}

$labels = ['Benutzer', 'Bestellungen'];
$i = 0;

// Jedes Ergebnis einzeln abholen
while ($result = pg_get_result($conn)) {
    if (pg_result_status($result) === PGSQL_TUPLES_OK) {
        $row = pg_fetch_assoc($result);
        echo $labels[$i] . ': ' . $row['anzahl'] . PHP_EOL;
    }
    pg_free_result($result);
    $i++;
}

pg_close($conn);

Benutzer: 42 Bestellungen: 137

// Wichtig · Fallstricke

SQL-Injection: Da pg_send_query() keine parameterisierten Abfragen unterstützt, dürfen Benutzereingaben niemals direkt in den Abfrage-String interpoliert werden. Verwende stattdessen pg_send_query_params() mit Platzhaltern ($1, $2, …) und einem separaten Parameter-Array.

Verbindungsstatus: Wenn die Verbindung bereits auf ein Ergebnis einer vorherigen asynchronen Abfrage wartet (pg_connection_busy() gibt true zurück), schlägt pg_send_query() fehl. Alle ausstehenden Ergebnisse müssen zunächst mit pg_get_result() abgeholt werden.

Objekt-API ab PHP 8.1: Der Parameter $connection ist seit PHP 8.1 ein PgSql\Connection-Objekt; in älteren Versionen war es eine resource.

Siehe auch

pg_query pg_send_query_params pg_get_result pg_connection_busy pg_cancel_query pg_result_status pg_last_error