pg_prepare — Funktion · PHP-Referenz

Signatur

pg_prepare(PgSql\Connection $connection = ?, string $statement_name, string $query): PgSql\Result|false

Beschreibung

pg_prepare() sendet eine Anfrage an den PostgreSQL-Server, eine benannte vorbereitete Anweisung (Prepared Statement) zu erzeugen. Das SQL-Statement wird dabei einmalig geparst und compiliert, sodass es später mit pg_execute() beliebig oft mit unterschiedlichen Parametern ausgeführt werden kann, ohne erneut übertragen zu werden.

Prepared Statements bieten zwei wesentliche Vorteile: Erstens verbessern sie die Performance bei wiederholter Ausführung desselben Statements erheblich, da der Parser- und Planungsaufwand entfällt. Zweitens verhindern sie SQL-Injection-Angriffe zuverlässig, da Parameter niemals direkt in den SQL-Text eingebettet werden, sondern separat als $1, $2, ... Platzhalter übergeben werden.

Der Name der Anweisung ($statement_name) muss pro Verbindung eindeutig sein. Ein leerer String '' erzeugt die unbenannte vorbereitete Anweisung, die bei der nächsten Ausführung von pg_prepare() mit leerem Namen überschrieben wird. Mit pg_execute() wird die vorbereitete Anweisung anschließend mit konkreten Parameterwerten ausgeführt.

Die Funktion ist nur für PostgreSQL-Verbindungen verfügbar und erfordert mindestens PostgreSQL 7.4 auf Serverseite.

Parameter

Name	Typ	Beschreibung
$connection	PgSql\Connection	Eine PostgreSQL-Verbindungsinstanz (`PgSql\Connection`). Wird dieser Parameter weggelassen, wird die zuletzt mit `pg_connect()` oder `pg_pconnect()` geöffnete Verbindung verwendet.
$statement_name Pflicht	string	Der Name, unter dem die vorbereitete Anweisung auf dem Server gespeichert wird. Ein leerer String `''` erzeugt die unbenannte vorbereitete Anweisung der Verbindung. Der Name muss pro Verbindung eindeutig sein.
$query Pflicht	string	Die parametrisierte SQL-Anweisung. Parameter werden als `$1`, `$2`, ... angegeben und später bei `pg_execute()` durch tatsächliche Werte ersetzt. Es darf nur eine einzige SQL-Anweisung übergeben werden.

Rückgabewert

Typ

PgSql\Result|false

Beschreibung

Gibt bei Erfolg ein PgSql\Result-Objekt zurück (seit PHP 8.1; zuvor eine Ressource). Im Fehlerfall wird false zurückgegeben, z. B. wenn die Verbindung ungültig ist, der Name bereits vergeben ist oder das SQL syntaktisch fehlerhaft ist.

Beispiele

Grundlegende Verwendung mit pg_execute

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

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

// Vorbereitete Anweisung erstellen
$result = pg_prepare($conn, 'get_user_by_id', 'SELECT id, name, email FROM users WHERE id = $1');

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

// Anweisung mit konkreten Parametern ausführen
$res = pg_execute($conn, 'get_user_by_id', [42]);

while ($row = pg_fetch_assoc($res)) {
    echo 'ID: ' . $row['id'] . ', Name: ' . $row['name'] . PHP_EOL;
}

pg_close($conn);

ID: 42, Name: Max Mustermann

Mehrfache Ausführung desselben Prepared Statements

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

// INSERT-Anweisung vorbereiten
$prep = pg_prepare(
    $conn,
    'insert_order',
    'INSERT INTO orders (customer_id, product_id, quantity) VALUES ($1, $2, $3)'
);

if ($prep === false) {
    die('Fehler beim Vorbereiten: ' . pg_last_error($conn));
}

// Mehrere Datensätze effizient einfügen
$orders = [
    [101, 5, 2],
    [102, 8, 1],
    [103, 3, 5],
];

foreach ($orders as $order) {
    $res = pg_execute($conn, 'insert_order', $order);
    if ($res === false) {
        echo 'Fehler beim Einfügen: ' . pg_last_error($conn) . PHP_EOL;
    } else {
        echo 'Datensatz eingefügt.' . PHP_EOL;
    }
}

pg_close($conn);

Datensatz eingefügt. Datensatz eingefügt. Datensatz eingefügt.

Prepared Statement mit mehreren Parametern und Typangabe

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

// Suche mit mehreren Filtern vorbereiten
$prep = pg_prepare(
    $conn,
    'search_products',
    'SELECT id, name, price FROM products WHERE category = $1 AND price &lt;= $2 ORDER BY price ASC'
);

if ($prep === false) {
    die(pg_last_error($conn));
}

$res = pg_execute($conn, 'search_products', ['Elektronik', 199.99]);

$rows = pg_fetch_all($res);
foreach ($rows as $row) {
    printf("[%d] %s – %.2f EUR\n", $row['id'], $row['name'], $row['price']);
}

pg_close($conn);

[7] Bluetooth-Lautsprecher – 49.99 EUR [12] Kabelloser Kopfhörer – 129.00 EUR [3] Tablet-Halterung – 19.90 EUR

// Wichtig · Fallstricke

SQL-Injection-Schutz: Durch die Verwendung von Prepared Statements mit Platzhaltern ($1, $2, ...) werden Benutzereingaben niemals direkt im SQL-Text eingefügt. Dies ist die sicherste Methode, SQL-Injection zu verhindern – deutlich zuverlässiger als manuelles Escaping mit pg_escape_string().

Namenskonflikte: Wird pg_prepare() zweimal mit demselben Namen aufgerufen, liefert der Server einen Fehler. Nutze pg_query() mit DEALLOCATE name, um ein vorhandenes Statement freizugeben, oder wähle eindeutige Namen (z. B. per Präfix oder UUID).

Einschränkung auf eine Anweisung: Im Gegensatz zu pg_query() darf $query nur eine einzige SQL-Anweisung enthalten. Mehrere durch Semikolon getrennte Statements werden abgelehnt.

Serveranforderung: Die Funktion benötigt PostgreSQL Server 7.4 oder neuer. Ältere Server unterstützen keine serverseitigen Prepared Statements.

Siehe auch

pg_execute pg_query_params pg_query pg_connect pg_last_error pg_fetch_assoc