pg_query_params — Funktion · PHP-Referenz

Signatur

pg_query_params(PgSql\Connection|string $connection, string $query, array $params): PgSql\Result|false

Beschreibung

pg_query_params() ist das PostgreSQL-Äquivalent zu Prepared Statements mit eingebetteten Parametern: Das SQL-Kommando und die zugehörigen Werte werden in getrennten Argumenten an den Server gesendet. Der Server verhindert dadurch automatisch SQL-Injection, da Parameter niemals in den SQL-Text interpoliert werden.

Im SQL-String werden Platzhalter als $1, $2, $3 usw. geschrieben. Die zugehörigen Werte werden im $params-Array in derselben Reihenfolge übergeben. Im Gegensatz zu pg_prepare() / pg_execute() muss die Abfrage nicht vorher vorbereitet werden, was sie für einmalig ausgeführte Abfragen einfacher macht.

Die Funktion akzeptiert optional als erstes Argument eine Datenbankverbindung (PgSql\Connection). Fehlt diese, wird die zuletzt geöffnete Verbindung verwendet. Das zurückgegebene Ergebnis-Ressource-Objekt (PgSql\Result) kann anschließend mit Funktionen wie pg_fetch_assoc(), pg_fetch_row() usw. ausgelesen werden.

Einschränkung: Je Aufruf kann nur ein einzelnes SQL-Kommando gesendet werden. Für mehrere Kommandos in einem Aufruf muss pg_query() verwendet werden — allerdings ohne Parameter-Trennung und damit ohne den Sicherheitsgewinn.

Parameter

Name	Typ	Beschreibung
$connection	PgSql\Connection\|string	Eine PostgreSQL-Datenbankverbindung (`PgSql\Connection`). Wird kein Verbindungs-Objekt übergeben, wird die zuletzt mit `pg_connect()` geöffnete Verbindung genutzt. Seit PHP 8.1 ist dieser Parameter ein `PgSql\Connection`-Objekt; vorher war es eine Ressource.
$query Pflicht	string	Das SQL-Kommando als Zeichenkette. Platzhalter für Parameter werden als `$1`, `$2`, `$3` usw. angegeben. Es darf nur ein einziges SQL-Kommando enthalten sein.
$params Pflicht	array	Ein indiziertes Array mit den Werten, die anstelle der Platzhalter (`$1`, `$2`, …) eingesetzt werden. Die Reihenfolge im Array entspricht der Nummerierung der Platzhalter. `null`-Werte werden als SQL-`NULL` übermittelt.

Rückgabewert

Typ

PgSql\Result|false

Beschreibung

Bei Erfolg ein PgSql\Result-Objekt (vor PHP 8.1 eine Ressource), das mit pg_fetch_assoc(), pg_num_rows() o. ä. weiterverarbeitet werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

Einfache SELECT-Abfrage mit einem Parameter

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

$userId = 42;
$result = pg_query_params($conn, 'SELECT id, name, email FROM users WHERE id = $1', [$userId]);

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

$row = pg_fetch_assoc($result);
if ($row) {
    echo 'Name: ' . $row['name'] . PHP_EOL;
    echo 'E-Mail: ' . $row['email'] . PHP_EOL;
} else {
    echo 'Kein Benutzer gefunden.';
}

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

Name: Max Mustermann E-Mail: max@example.com

INSERT mit mehreren Parametern und NULL-Übergabe

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

$name    = "Erika Musterfrau";
$email   = "erika@example.com";
$phone   = null; // Telefonnummer unbekannt -> SQL NULL
$role    = "customer";

$sql = 'INSERT INTO users (name, email, phone, role) VALUES ($1, $2, $3, $4) RETURNING id';
$result = pg_query_params($conn, $sql, [$name, $email, $phone, $role]);

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

$row = pg_fetch_assoc($result);
echo 'Neuer Benutzer angelegt mit ID: ' . $row['id'] . PHP_EOL;

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

Neuer Benutzer angelegt mit ID: 101

Suche mit LIKE-Muster und mehreren Parametern

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

$suchbegriff = 'Muster'; // Benutzereingabe — sicher übergeben
$minId       = 10;

// % muss Teil des Parameterwerts sein, NICHT im SQL-Text
$result = pg_query_params(
    $conn,
    'SELECT id, name FROM users WHERE name ILIKE $1 AND id &gt;= $2 ORDER BY name',
    ['%' . $suchbegriff . '%', $minId]
);

while ($row = pg_fetch_assoc($result)) {
    echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
}

pg_free_result($result);

42: Max Mustermann 101: Erika Musterfrau

// Wichtig · Fallstricke

Sicherheit: pg_query_params() schützt zuverlässig vor SQL-Injection, da Parameter niemals in den SQL-Text eingebettet werden. Es ist daher pg_query() mit manuell eingefügten, per pg_escape_string() maskierten Werten klar vorzuziehen.

LIKE-Muster: Prozenzeichen (%) und Unterstriche (_) innerhalb eines Parameters behalten ihre besondere Bedeutung für LIKE/ILIKE. Sollen sie als Literalzeichen gelten, müssen sie im PHP-Code mit \% bzw. \_ maskiert werden — der Parameterschutz verhindert lediglich SQL-Injection, nicht die LIKE-Metazeichen-Semantik.

Nur ein Kommando pro Aufruf: Anders als pg_query() unterstützt pg_query_params() kein Semikolon-getrennte Mehrfach-Kommandos in einem Aufruf. Dies ist eine Einschränkung der PostgreSQL-libpq-Protokollebene für parametrisierte Abfragen.

Typ-Casting: Alle Parameter werden standardmäßig als Zeichenketten gesendet. PostgreSQL konvertiert sie automatisch in den benötigten Typ. Sollte eine explizite Typangabe nötig sein, kann Casting im SQL direkt verwendet werden, z. B. $1::integer.

Siehe auch

pg_connect pg_query pg_prepare pg_execute pg_fetch_assoc pg_fetch_row pg_last_error pg_free_result pg_escape_string