pg_send_query_params — Funktion · PHP-Referenz

Signatur

pg_send_query_params(PgSql\Connection $connection, string $query, array $params): int|false

Beschreibung

pg_send_query_params() ist die asynchrone Variante von pg_query_params(). Die Funktion schickt ein SQL-Kommando zusammen mit seinen Parametern an den PostgreSQL-Server und kehrt sofort zurück, ohne auf das Ergebnis zu warten. Dadurch kann das PHP-Skript in der Zwischenzeit andere Aufgaben erledigen. Das Ergebnis wird später mit pg_get_result() abgerufen.

Ein entscheidender Sicherheitsvorteil liegt in der Trennung von SQL-Kommando und Parametern: PostgreSQL behandelt die übergebenen Werte intern als Literale, sodass SQL-Injection strukturell verhindert wird – ein manuelles Escaping der Parameter ist nicht erforderlich. Die Parameter werden im $params-Array als numerisch indiziertes Array übergeben und im Query als $1, $2, … referenziert.

Die Funktion eignet sich besonders für Szenarien, in denen mehrere Datenbankoperationen parallel angestoßen werden sollen (z. B. mehrere asynchrone Abfragen nacheinander senden und die Ergebnisse gebündelt abrufen) oder wenn die Anwendung während des Wartens auf die Datenbank weiterarbeiten soll.

Wichtig: Es kann immer nur eine aktive asynchrone Anfrage pro Verbindung geben. Eine neue Anfrage kann erst gestellt werden, wenn alle Ergebnisse der vorherigen Anfrage mit pg_get_result() vollständig abgerufen wurden.

Parameter

Name	Typ	Beschreibung
$connection Pflicht	PgSql\Connection	Eine aktive PostgreSQL-Datenbankverbindung, die zuvor mit `pg_connect()` oder `pg_pconnect()` erzeugt wurde.
$query Pflicht	string	Das SQL-Kommando als Zeichenkette. Parameter werden als Platzhalter `$1`, `$2` usw. angegeben. Es darf nur ein einziges SQL-Kommando übergeben werden (kein Semikolon-getrenntes Multi-Statement).
$params Pflicht	array	Ein numerisch indiziertes Array mit den Parameterwerten, die den Platzhaltern `$1`, `$2` usw. entsprechen. Werte werden als Zeichenketten übergeben; `null` wird als SQL-`NULL` behandelt.

Rückgabewert

Typ

int|false

Beschreibung

Gibt 1 zurück, wenn die Anfrage erfolgreich an den Server gesendet wurde, oder false im Fehlerfall (z. B. keine Verbindung, ungültige Parameter). Ein Rückgabewert von 1 bedeutet nicht, dass die Abfrage erfolgreich ausgeführt wurde – das eigentliche Ergebnis muss mit pg_get_result() geprüft werden.

Beispiele

Asynchrone parametrisierte Abfrage senden und Ergebnis abrufen

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

$userId = 42;
$status = 'active';

// Asynchron senden – kehrt sofort zurück
$sent = pg_send_query_params(
    $conn,
    'SELECT id, name, email FROM users WHERE id = $1 AND status = $2',
    [$userId, $status]
);

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

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

// Ergebnis abrufen (blockiert bis zum Ende der Abfrage)
$result = pg_get_result($conn);
if (!$result || pg_result_status($result) !== PGSQL_TUPLES_OK) {
    die('Abfragefehler: ' . pg_result_error($result));
}

$rows = pg_fetch_all($result);
foreach ($rows as $row) {
    echo $row['id'] . ': ' . $row['name'] . ' (' . $row['email'] . ')' . PHP_EOL;
}

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

42: Max Mustermann (max@example.com)

Mehrere asynchrone Abfragen sequenziell senden

<?php
$conn = pg_connect('host=localhost dbname=shop user=app password=geheim');

$queries = [
    ['SELECT count(*) AS cnt FROM orders WHERE user_id = $1', [1]],
    ['SELECT count(*) AS cnt FROM orders WHERE user_id = $1', [2]],
];

foreach ($queries as [$sql, $params]) {
    if (!pg_send_query_params($conn, $sql, $params)) {
        echo 'Senden fehlgeschlagen: ' . pg_last_error($conn) . PHP_EOL;
        continue;
    }

    // Alle Ergebnisse der aktuellen Abfrage abrufen,
    // bevor die nächste gesendet werden kann.
    while ($result = pg_get_result($conn)) {
        if (pg_result_status($result) === PGSQL_TUPLES_OK) {
            $row = pg_fetch_assoc($result);
            echo 'Anzahl: ' . $row['cnt'] . PHP_EOL;
        } else {
            echo 'Fehler: ' . pg_result_error($result) . PHP_EOL;
        }
        pg_free_result($result);
    }
}

pg_close($conn);

Anzahl: 5 Anzahl: 3

// Wichtig · Fallstricke

Sicherheit: Da SQL-Kommando und Parameter getrennt übertragen werden, ist SQL-Injection durch externe Eingaben strukturell ausgeschlossen – sofern die Parameter korrekt im $params-Array übergeben werden und nicht direkt in den Query-String interpoliert werden.

Nur ein Kommando: Im Gegensatz zu pg_send_query() erlaubt pg_send_query_params() nur genau ein SQL-Statement. Der Versuch, mehrere durch Semikolon getrennte Kommandos zu senden, führt zu einem Fehler.

Verbindungsstatus: Vor dem Senden einer neuen asynchronen Abfrage müssen alle ausstehenden Ergebnisse der vorherigen Abfrage mit pg_get_result() vollständig konsumiert werden, sonst schlägt der neue Sendeversuch fehl.

PHP 8.1+: Ab PHP 8.1 ist der Verbindungsparameter ein PgSql\Connection-Objekt; in früheren Versionen war es eine resource.

Siehe auch

pg_send_query pg_query_params pg_get_result pg_connect pg_result_status pg_last_error pg_send_prepare pg_send_execute