pg_send_execute — Funktion · PHP-Referenz

Signatur

pg_send_execute(PgSql\Connection $connection, string $stmtname, array $params): int|false

Beschreibung

pg_send_execute() ist die asynchrone Variante von pg_execute(). Die Funktion sendet die Ausführungsanforderung für eine zuvor mit pg_prepare() (oder pg_send_prepare()) vorbereitete Abfrage an den PostgreSQL-Server und kehrt sofort zurück, ohne auf die Antwort des Servers zu warten. Das Ergebnis der Ausführung kann anschließend mit pg_get_result() abgeholt werden.

Dieser nicht-blockierende Ansatz ist besonders nützlich, wenn mehrere Datenbankoperationen parallel oder in Verbindung mit anderen I/O-Operationen ausgeführt werden sollen. Die Anwendung kann nach dem Senden der Anfrage andere Aufgaben erledigen und das Ergebnis erst dann abrufen, wenn es benötigt wird.

Alle Parameterwerte werden getrennt vom SQL-Text übertragen, was SQL-Injection von Haus aus verhindert — Werte werden niemals direkt in den SQL-String eingebettet. Jeder Platzhalter im vorbereiteten Statement ($1, $2, …) entspricht einem Element im $params-Array.

Wichtig: Auf einer Verbindung darf immer nur eine asynchrone Anfrage gleichzeitig aktiv sein. Bevor eine neue asynchrone Anfrage gesendet wird, muss das Ergebnis der vorherigen vollständig mit pg_get_result() ausgelesen worden sein.

Parameter

Name	Typ	Beschreibung
$connection Pflicht	PgSql\Connection	Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$stmtname Pflicht	string	Der Name des vorbereiteten Statements, das ausgeführt werden soll. Der leere String (`""`) referenziert das zuletzt mit `pg_prepare()` erstellte unbenannte Statement.
$params Pflicht	array	Ein Array mit Parameterwerten, die die Platzhalter `$1`, `$2`, … im vorbereiteten Statement ersetzen. Anzahl und Reihenfolge müssen mit den Platzhaltern übereinstimmen. `null`-Werte werden als SQL-`NULL` übertragen.

Rückgabewert

Typ

int|false

Beschreibung

Gibt 1 zurück, wenn die Anfrage erfolgreich an den Server gesendet wurde, oder false bei einem Fehler (z. B. wenn bereits eine asynchrone Anfrage aussteht oder die Verbindung ungültig ist). Das tatsächliche Abfrageergebnis muss anschließend mit pg_get_result() abgerufen werden.

Beispiele

Asynchrone Ausführung eines vorbereiteten Statements

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

// Statement vorbereiten
$prep = pg_prepare($conn, 'find_user', 'SELECT id, username, email FROM users WHERE id = $1');
if (!$prep) {
    die('Vorbereitung fehlgeschlagen: ' . pg_last_error($conn));
}

// Asynchron ausführen
$sent = pg_send_execute($conn, 'find_user', [42]);
if ($sent === false) {
    die('Senden fehlgeschlagen: ' . pg_last_error($conn));
}

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

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

$row = pg_fetch_assoc($result);
if ($row) {
    echo 'Benutzer: ' . $row['username'] . ' (' . $row['email'] . ")\
";
} else {
    echo 'Kein Benutzer mit dieser ID gefunden.' . "\
";
}

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

Benutzer: max.mustermann (max@example.com)

Mehrere asynchrone Anfragen sequenziell verarbeiten

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');

// Statement für Einfügeoperation vorbereiten
pg_prepare($conn, 'insert_log', 'INSERT INTO access_log (user_id, action, ts) VALUES ($1, $2, NOW())');

$entries = [
    [1, 'login'],
    [2, 'view_dashboard'],
    [3, 'logout'],
];

foreach ($entries as $entry) {
    // Asynchron senden
    if (!pg_send_execute($conn, 'insert_log', $entry)) {
        echo 'Fehler beim Senden: ' . pg_last_error($conn) . "\
";
        continue;
    }

    // Ergebnis der aktuellen Anfrage vollständig abholen,
    // bevor die nächste asynchrone Anfrage gesendet wird
    $result = pg_get_result($conn);
    if (pg_result_status($result) === PGSQL_COMMAND_OK) {
        echo 'Eintrag für user_id=' . $entry[0] . ' gespeichert.' . "\
";
    } else {
        echo 'Fehler: ' . pg_result_error($result) . "\
";
    }
    pg_free_result($result);
}

pg_close($conn);

Eintrag für user_id=1 gespeichert. Eintrag für user_id=2 gespeichert. Eintrag für user_id=3 gespeichert.

// Wichtig · Fallstricke

Gleichzeitige Anfragen: Auf einer Verbindung kann immer nur eine asynchrone Anfrage gleichzeitig offen sein. Das Senden einer neuen Anfrage, bevor alle Ergebnisse der vorherigen mit pg_get_result() vollständig abgerufen wurden, schlägt fehl.

Sicherheit: Da Parameter getrennt vom SQL-Text übermittelt werden, ist SQL-Injection strukturell ausgeschlossen. Es sind keine zusätzlichen Escape-Maßnahmen für Parameterwerte erforderlich.

Fehlerbehandlung: Der Rückgabewert von pg_send_execute() zeigt nur an, ob die Anfrage erfolgreich an den Server gesendet wurde. Ob die Abfrage serverseitig erfolgreich war, lässt sich erst nach dem Aufruf von pg_get_result() über pg_result_status() und pg_result_error() ermitteln.

Verbindungsmodus: Damit asynchrone Funktionen korrekt funktionieren, sollte die Verbindung nicht im blockierenden Modus betrieben werden. Mit pg_socket() und stream_select() kann auf Lesbarkeit gewartet werden, bevor pg_get_result() aufgerufen wird.

Siehe auch

pg_send_prepare pg_send_query_params pg_get_result pg_prepare pg_execute pg_result_status pg_last_error