pg_send_prepare — Funktion · PHP-Referenz

Signatur

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

Beschreibung

pg_send_prepare() ist die nicht-blockierende Variante von pg_prepare(). Die Funktion sendet den Befehl zur Erstellung eines Prepared Statements an den PostgreSQL-Server und kehrt sofort zurück, ohne auf die Antwort des Servers zu warten. Dies erlaubt es, andere Aufgaben auszuführen, während der Server die Anfrage verarbeitet.

Das Ergebnis der asynchronen Operation muss anschließend mit pg_get_result() abgerufen werden. Mit pg_connection_busy() kann geprüft werden, ob die Verbindung noch beschäftigt ist, bevor das Ergebnis abgeholt wird. Sobald das Prepared Statement erfolgreich erstellt wurde, kann es mit pg_send_execute() oder pg_execute() ausgeführt werden.

Asynchrone Datenbankoperationen eignen sich besonders in Szenarien, in denen die Anwendung nicht blockieren soll – etwa in ereignisgesteuerten oder nicht-blockierenden Architekturen, oder wenn mehrere Datenbankoperationen parallel vorbereitet werden sollen. In typischen synchronen PHP-Skripten wird meist pg_prepare() bevorzugt.

Prepared Statements schützen grundsätzlich vor SQL-Injection, da Benutzereingaben als Parameter und nicht als Teil des SQL-Textes übergeben werden.

Parameter

Name	Typ	Beschreibung
$connection Pflicht	PgSql\Connection	Eine aktive PostgreSQL-Datenbankverbindung, die zuvor mit `pg_connect()` oder `pg_pconnect()` geöffnet wurde.
$statement_name Pflicht	string	Der Name, unter dem das Prepared Statement gespeichert werden soll. Ein leerer String `""` erzeugt ein unbenanntes Statement, das sofort das vorherige unbenannte Statement ersetzt.
$query Pflicht	string	Der SQL-Befehl, der als Prepared Statement vorbereitet werden soll. Platzhalter für Parameter werden als `$1`, `$2` usw. angegeben. Es darf nur ein einzelner SQL-Befehl übergeben werden.

Rückgabewert

Typ

int|false

Beschreibung

Gibt 1 zurück, wenn die Anfrage erfolgreich an den Server gesendet wurde (nicht, dass sie erfolgreich verarbeitet wurde), oder false bei einem Fehler, z. B. wenn die Verbindung ungültig oder beschäftigt ist. Das eigentliche Ergebnis der Vorbereitung muss mit pg_get_result() abgerufen und überprüft werden.

Beispiele

Asynchrones Prepared Statement erstellen und ausführen

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

if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Asynchrones Senden der Prepare-Anfrage
$sent = pg_send_prepare($conn, 'get_user', 'SELECT id, name, email FROM users WHERE id = $1');

if ($sent === false) {
    die('pg_send_prepare fehlgeschlagen: ' . pg_last_error($conn));
}

// Warten bis die Verbindung nicht mehr beschäftigt ist
while (pg_connection_busy($conn)) {
    // optional: kurze Pause oder andere Aufgaben erledigen
}

// Ergebnis der Prepare-Operation abrufen und prüfen
$result = pg_get_result($conn);
if (!$result || pg_result_status($result) !== PGSQL_COMMAND_OK) {
    die('Fehler beim Vorbereiten: ' . pg_result_error($result));
}

echo "Prepared Statement erfolgreich erstellt.\n";

// Statement asynchron ausführen
pg_send_execute($conn, 'get_user', [42]);

while (pg_connection_busy($conn)) {}

$execResult = pg_get_result($conn);
while ($row = pg_fetch_assoc($execResult)) {
    echo "ID: {$row['id']}, Name: {$row['name']}, E-Mail: {$row['email']}\n";
}

pg_free_result($execResult);
pg_close($conn);

Prepared Statement erfolgreich erstellt. ID: 42, Name: Max Mustermann, E-Mail: max@example.com

Mehrere Prepared Statements asynchron vorbereiten

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

$statements = [
    'find_by_email' => 'SELECT id, name FROM users WHERE email = $1',
    'count_orders'  => 'SELECT COUNT(*) FROM orders WHERE user_id = $1',
];

foreach ($statements as $name => $sql) {
    if (!pg_send_prepare($conn, $name, $sql)) {
        die("Fehler beim Senden von '$name': " . pg_last_error($conn));
    }

    while (pg_connection_busy($conn)) {}

    $res = pg_get_result($conn);
    if (pg_result_status($res) !== PGSQL_COMMAND_OK) {
        die("Prepare '$name' fehlgeschlagen: " . pg_result_error($res));
    }
    echo "Statement '$name' vorbereitet.\n";
}

echo "Alle Statements bereit.\n";
pg_close($conn);

Statement 'find_by_email' vorbereitet. Statement 'count_orders' vorbereitet. Alle Statements bereit.

// Wichtig · Fallstricke

Sicherheit: Obwohl Prepared Statements SQL-Injection verhindern, sollte der $statement_name selbst keine Benutzereingaben enthalten, da er kein parametrisierter Wert ist.

Verbindungsstatus: Es darf immer nur eine asynchrone Operation gleichzeitig auf einer Verbindung aktiv sein. Vor dem Aufruf von pg_send_prepare() sollte mit pg_connection_busy() sichergestellt werden, dass die Verbindung frei ist. Andernfalls gibt die Funktion false zurück.

Ergebnis nicht vergessen: Das Ergebnis muss zwingend mit pg_get_result() abgeholt werden, auch wenn es nicht weiter ausgewertet wird – sonst kann die Verbindung in einem inkonsistenten Zustand verbleiben.

PHP 8.1+: Ab PHP 8.1 ist der Rückgabetyp der Verbindung PgSql\Connection statt resource.

Siehe auch

pg_prepare pg_send_execute pg_send_query pg_get_result pg_connection_busy pg_execute pg_result_status